deeplink-parity 0.3.0 → 0.4.0

package/README.md

@@ -97,7 +97,18 @@ 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.
 
-Exits `1` when there is at least one error, so it drops into CI unchanged.
+### In CI
+
+| Exit code | Meaning |
+|---|---|
+| `0` | No errors. Warnings and notices do not fail the run |
+| `1` | At least one error — a link is broken today |
+| `2` | Nothing to check, or the run itself failed |
+
+Colour is emitted only to a terminal, so piped and captured output stays plain. `--json`
+writes nothing but JSON to stdout; progress notes go to stderr. On GitHub Actions the
+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
 

package/dist/cli.js

@@ -2,6 +2,7 @@
 import { resolve } from 'node:path';
 import { localSource, networkSource } from './fetch/wellKnown.js';
 import { exitCodeFor, printReport } from './report/console.js';
+import { printGithubAnnotations } from './report/github.js';
 import { run } from './run.js';
 const USAGE = `deeplink-parity — check that what your app declares about deep links
 matches what is actually hosted, across iOS and Android.
@@ -18,6 +19,7 @@ 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
+  --format github          GitHub Actions annotations (auto-detected on Actions)
   -h, --help               Show this message
 `;
 function parseArgs(argv) {
@@ -27,6 +29,8 @@ function parseArgs(argv) {
     let help = false;
     let sha256;
     let wellKnown;
+    // 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++) {
         const arg = args[i];
         if (arg === '--json')
@@ -37,6 +41,8 @@ function parseArgs(argv) {
             sha256 = args[++i];
         else if (arg === '--well-known')
             wellKnown = args[++i];
+        else if (arg === '--format')
+            format = args[++i];
         else if (!arg.startsWith('-'))
             roots.push(arg);
     }
@@ -46,16 +52,27 @@ function parseArgs(argv) {
         help,
         sha256,
         wellKnown,
+        format,
     };
 }
 async function main() {
-    const { roots, json, help, sha256, wellKnown } = parseArgs(process.argv);
+    const { roots, json, help, sha256, wellKnown, format } = parseArgs(process.argv);
     if (help) {
         console.log(USAGE);
         return;
     }
     const source = wellKnown ? localSource(resolve(wellKnown)) : networkSource();
-    const result = await run({ roots, source, sha256 });
+    const result = await run({
+        roots,
+        source,
+        sha256,
+        onDiscovered: (count) => {
+            // some apps declare a domain per country; say so before spending minutes on it
+            if (!wellKnown && count > 50) {
+                console.error(`Checking ${count} domains — requests are pooled, so this will take a while.`);
+            }
+        },
+    });
     if (result.iosApps.length === 0 && result.androidApps.length === 0 && result.findings.length === 0) {
         console.error(`No app configuration declaring deep links was found in ${roots.join(', ')}`);
         console.error('Expected a .entitlements file with applinks:, or an AndroidManifest.xml with intent-filters.');
@@ -77,6 +94,10 @@ async function main() {
             findings: result.findings,
         }, null, 2));
     }
+    else if (format === 'github') {
+        printGithubAnnotations(result.findings);
+        printReport(result.findings, result.domains);
+    }
     else {
         printReport(result.findings, result.domains);
     }

package/dist/fetch/wellKnown.js

@@ -1,6 +1,12 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 const TIMEOUT_MS = 10_000;
+/**
+ * Identify the tool to the hosts being read. An operator seeing these requests in a log
+ * should be able to tell what they are and who to ask, rather than finding an anonymous
+ * Node default.
+ */
+const USER_AGENT = 'deeplink-parity (+https://github.com/camosss/deeplink-parity)';
 export const AASA_FILE = 'apple-app-site-association';
 export const ASSETLINKS_FILE = 'assetlinks.json';
 export function aasaUrl(domain) {
@@ -20,7 +26,7 @@ async function fetchRaw(url) {
         const res = await fetch(url, {
             redirect: 'manual',
             signal: controller.signal,
-            headers: { accept: 'application/json' },
+            headers: { accept: 'application/json', 'user-agent': USER_AGENT },
         });
         const redirected = res.status >= 300 && res.status < 400;
         return {

package/dist/report/console.js

@@ -11,7 +11,9 @@ const ORDER = ['error', 'warn', 'info'];
 const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
 const paint = (s, c) => (useColor ? `${c}${s}${RESET}` : s);
 export function printReport(findings, checkedDomains) {
-    console.log(`\n${paint('deeplink-parity', BOLD)} ${DIM}·${RESET} ${checkedDomains.length} domain(s) checked\n`);
+    // every escape goes through paint(), which is a no-op when stdout is not a terminal
+    const separator = paint('·', DIM);
+    console.log(`\n${paint('deeplink-parity', BOLD)} ${separator} ${checkedDomains.length} domain(s) checked\n`);
     if (findings.length === 0) {
         console.log(paint('No problems found', ''));
         console.log();

package/dist/report/github.js

@@ -0,0 +1,31 @@
+import { isAbsolute } from 'node:path';
+const LEVEL = {
+    error: 'error',
+    warn: 'warning',
+    info: 'notice',
+};
+/** Workflow commands treat these characters as syntax and need them escaped. */
+function escapeData(value) {
+    return value.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+}
+function escapeProperty(value) {
+    return escapeData(value).replace(/:/g, '%3A').replace(/,/g, '%2C');
+}
+/**
+ * GitHub Actions annotation format, so findings appear on the run summary — and on the
+ * changed lines when a finding points at a file in the repository.
+ * https://docs.github.com/actions/reference/workflow-commands-for-github-actions
+ */
+export function printGithubAnnotations(findings) {
+    for (const f of findings) {
+        const props = [`title=${escapeProperty(`deeplink-parity ${f.rule}`)}`];
+        // Annotations anchor to a path inside the checkout. A source can also be a URL or an
+        // absolute path outside it — neither anchors to anything, so the annotation stays
+        // on the run summary instead of pointing at a file that will not resolve.
+        if (f.source && !/^https?:\/\//.test(f.source) && !isAbsolute(f.source)) {
+            props.push(`file=${escapeProperty(f.source)}`);
+        }
+        const body = [f.domain, f.message, f.detail].filter(Boolean).join(' — ');
+        console.log(`::${LEVEL[f.severity]} ${props.join(',')}::${escapeData(body)}`);
+    }
+}

package/dist/run.js

@@ -9,7 +9,7 @@ import { isWildcardDomain, wildcardFinding } from './rules/wildcard.js';
 function emptyView() {
     return { domains: new Set(), paths: new Map() };
 }
-export async function run({ roots, source, sha256 }) {
+export async function run({ roots, source, sha256, onDiscovered }) {
     const discovered = await Promise.all(roots.map(async (root) => Promise.all([discoverIos(root), discoverAndroid(root)])));
     const iosApps = discovered.flatMap(([ios]) => ios);
     const androidApps = discovered.flatMap(([, android]) => android);
@@ -21,6 +21,10 @@ export async function run({ roots, source, sha256 }) {
     }
     const ios = emptyView();
     const android = emptyView();
+    onDiscovered?.(new Set([
+        ...iosApps.flatMap((a) => a.domains),
+        ...androidApps.flatMap((a) => a.hosts.map((h) => h.host)),
+    ]).size);
     for (const app of iosApps) {
         // the same domain can be declared by several targets; fetch it once
         const fresh = app.domains.filter((d) => !ios.domains.has(d));

package/package.json

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