deeplink-parity 0.4.0 → 0.5.1

package/README.md

@@ -9,8 +9,7 @@
 Checks that what your app **declares** about deep links matches what is actually **hosted** — on both iOS and Android, from one command.
 
 ```bash
-# iOS and Android usually live in separate repositories — pass both
-npx deeplink-parity ./my-app-ios ./my-app-android
+npx deeplink-parity .
 ```
 
 ```
@@ -30,6 +29,53 @@ WARN   promo.example.com
 
 <br>
 
+## Quick start
+
+Nothing to configure. Domains are read from your app and the matching files are fetched
+from them.
+
+**One repository** — a monorepo, Flutter, or React Native:
+
+```bash
+npx deeplink-parity .
+```
+
+**Two repositories** — native iOS and Android, which is the case worth checking:
+
+```bash
+npx deeplink-parity ./my-app-ios ./my-app-android
+```
+
+**On GitHub Actions**, one line:
+
+```yaml
+- uses: actions/checkout@v4
+- uses: camosss/deeplink-parity@v1
+```
+
+Findings show up as annotations on the run. Add `sha256` to include the Android signing
+key in the check, and `fail-on: never` to report without failing while an existing backlog
+is cleared.
+
+<br>
+
+## Contents
+
+- [Why](#why)
+- [What it checks](#what-it-checks)
+- [Usage](#usage)
+  - [GitHub Action](#github-action)
+  - [In CI](#in-ci)
+  - [Run it on a schedule](#run-it-on-a-schedule)
+  - [Validate before deploying](#validate-before-deploying)
+- [Native, Flutter and React Native](#native-flutter-and-react-native)
+- [Hardened against real projects](#hardened-against-real-projects)
+- [What it does not do](#what-it-does-not-do)
+- [Development](#development)
+- [License](#license)
+
+<br>
+
 ## Why
 
 Deep links fail **silently**. There is no crash, no error log, no red test. A user taps a link, the browser opens instead of your app, and they shrug and move on. Nobody finds out for months.
@@ -81,7 +127,10 @@ npx deeplink-parity [path...] [options]
 
   --sha256 <fingerprint>   Android signing fingerprint to look for in assetlinks.json
   --well-known <dir>       Read well-known files from <dir>/<domain>/ instead of the network
-  --json                   Machine-readable output
+  --json                   Machine-readable output on stdout
+  --output <file>          Also write the JSON result to a file
+  --format github          GitHub Actions annotations (auto-detected on Actions)
+  -h, --help               Show this message
 ```
 
 Pass one path per checkout. A monorepo holding both platforms works as a single path,
@@ -97,6 +146,35 @@ npx deeplink-parity . --sha256 "AB:CD:…"               # include the fingerpri
 The Android signing fingerprint comes from Play Console → App integrity → App signing.
 Without it the fingerprint check is skipped and reported as such.
 
+### GitHub Action
+
+```yaml
+- uses: camosss/deeplink-parity@v1
+  with:
+    paths: ios android          # one per checkout; omit for a single repo
+    sha256: ${{ secrets.ANDROID_SHA256 }}
+```
+
+Findings appear as annotations on the run, and counts are available to later steps:
+
+```yaml
+- uses: camosss/deeplink-parity@v1
+  id: links
+  with:
+    fail-on: never              # report without blocking while a backlog is cleared
+- run: echo "${{ steps.links.outputs.errors }} errors, ${{ steps.links.outputs.warnings }} warnings"
+```
+
+| Input | Default | |
+|---|---|---|
+| `paths` | `.` | Checkout paths, whitespace separated |
+| `sha256` | — | Android signing fingerprint |
+| `well-known` | — | Read from disk instead of the network |
+| `fail-on` | `error` | `never` to report without failing the step |
+| `version` | pinned | npm version to run |
+
+Outputs: `errors`, `warnings`, `notices`, `domains`, `report` (path to the JSON result).
+
 ### In CI
 
 | Exit code | Meaning |
@@ -110,7 +188,7 @@ writes nothing but JSON to stdout; progress notes go to stderr. On GitHub Action
 findings are also emitted as annotations, which appear on the run summary and against the
 file when one is involved — set `--format github` to force it elsewhere.
 
-### Run it on a schedule — this is the point
+### Run it on a schedule
 
 Your deep-link configuration changes a few times a year. The things that break it do not live in your repo at all:
 
@@ -123,12 +201,26 @@ A pull-request check never sees any of this. **A daily scheduled run does.** See
 
 ### Validate before deploying
 
-`--well-known <dir>` reads the files from disk instead of the network, so the web team can check staged files before they ship — and CI can run with no egress.
+`--well-known <dir>` reads the files from disk instead of the network, so the web team can
+check staged files before they ship — and CI can run with no egress at all.
+
+```
+well-known/
+└── links.example.com/
+    ├── apple-app-site-association
+    └── assetlinks.json
+```
 
 ```bash
-npx deeplink-parity . --well-known ./staging/well-known
+npx deeplink-parity . --well-known ./well-known
 ```
 
+This answers a different question, though: whether the app matches the files you intend to
+publish, not whether it matches what is live right now. The failures this tool exists to
+catch — a deploy putting a redirect in front of `/.well-known/`, an expired domain, a
+rotated key — only show up against the real host. Files hosted by an attribution vendor
+cannot be checked offline at all.
+
 <br>
 
 ## Native, Flutter and React Native

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { localSource, networkSource } from './fetch/wellKnown.js';
 import { exitCodeFor, printReport } from './report/console.js';
@@ -18,7 +19,8 @@ Usage
 Options
   --sha256 <fingerprint>   Android signing fingerprint to look for in assetlinks.json
   --well-known <dir>       Read well-known files from <dir>/<domain>/ instead of the network
-  --json                   Machine-readable output
+  --json                   Machine-readable output on stdout
+  --output <file>          Also write the JSON result to a file
   --format github          GitHub Actions annotations (auto-detected on Actions)
   -h, --help               Show this message
 `;
@@ -29,6 +31,7 @@ function parseArgs(argv) {
     let help = false;
     let sha256;
     let wellKnown;
+    let output;
     // Actions sets GITHUB_ACTIONS=true; annotate by default there
     let format = process.env.GITHUB_ACTIONS === 'true' ? 'github' : 'console';
     for (let i = 0; i < args.length; i++) {
@@ -43,6 +46,8 @@ function parseArgs(argv) {
             wellKnown = args[++i];
         else if (arg === '--format')
             format = args[++i];
+        else if (arg === '--output')
+            output = args[++i];
         else if (!arg.startsWith('-'))
             roots.push(arg);
     }
@@ -53,10 +58,11 @@ function parseArgs(argv) {
         sha256,
         wellKnown,
         format,
+        output,
     };
 }
 async function main() {
-    const { roots, json, help, sha256, wellKnown, format } = parseArgs(process.argv);
+    const { roots, json, help, sha256, wellKnown, format, output } = parseArgs(process.argv);
     if (help) {
         console.log(USAGE);
         return;
@@ -78,27 +84,36 @@ async function main() {
         console.error('Expected a .entitlements file with applinks:, or an AndroidManifest.xml with intent-filters.');
         process.exit(2);
     }
+    const payload = {
+        ios: result.iosApps.map((a) => ({
+            entitlements: a.entitlementsPath,
+            teamId: a.teamId,
+            bundleId: a.bundleId,
+            domains: a.domains,
+        })),
+        android: result.androidApps.map((a) => ({
+            manifest: a.manifestPath,
+            packageIds: a.packageIds,
+            hosts: a.hosts.map((h) => h.host),
+        })),
+        summary: {
+            domains: result.domains.length,
+            error: result.findings.filter((f) => f.severity === 'error').length,
+            warn: result.findings.filter((f) => f.severity === 'warn').length,
+            info: result.findings.filter((f) => f.severity === 'info').length,
+        },
+        findings: result.findings,
+    };
+    // A file keeps stdout free, so annotations and the readable report can coexist with
+    // machine-readable output in the same run.
+    if (output)
+        await writeFile(output, `${JSON.stringify(payload, null, 2)}\n`);
     if (json) {
-        console.log(JSON.stringify({
-            ios: result.iosApps.map((a) => ({
-                entitlements: a.entitlementsPath,
-                teamId: a.teamId,
-                bundleId: a.bundleId,
-                domains: a.domains,
-            })),
-            android: result.androidApps.map((a) => ({
-                manifest: a.manifestPath,
-                packageIds: a.packageIds,
-                hosts: a.hosts.map((h) => h.host),
-            })),
-            findings: result.findings,
-        }, null, 2));
-    }
-    else if (format === 'github') {
-        printGithubAnnotations(result.findings);
-        printReport(result.findings, result.domains);
+        console.log(JSON.stringify(payload, null, 2));
     }
     else {
+        if (format === 'github')
+            printGithubAnnotations(result.findings);
         printReport(result.findings, result.domains);
     }
     process.exit(exitCodeFor(result.findings));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deeplink-parity",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Checks that what your mobile app declares about deep links matches what is actually hosted — across iOS and Android.",
   "type": "module",
   "bin": {