deeplink-parity 0.3.1 → 0.5.0

package/README.md

@@ -97,7 +97,47 @@ 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.
+### 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 |
+|---|---|
+| `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

@@ -1,7 +1,9 @@
 #!/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';
+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.
@@ -17,7 +19,9 @@ 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
 `;
 function parseArgs(argv) {
@@ -27,6 +31,9 @@ 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++) {
         const arg = args[i];
         if (arg === '--json')
@@ -37,6 +44,10 @@ function parseArgs(argv) {
             sha256 = args[++i];
         else if (arg === '--well-known')
             wellKnown = args[++i];
+        else if (arg === '--format')
+            format = args[++i];
+        else if (arg === '--output')
+            output = args[++i];
         else if (!arg.startsWith('-'))
             roots.push(arg);
     }
@@ -46,10 +57,12 @@ function parseArgs(argv) {
         help,
         sha256,
         wellKnown,
+        format,
+        output,
     };
 }
 async function main() {
-    const { roots, json, help, sha256, wellKnown } = parseArgs(process.argv);
+    const { roots, json, help, sha256, wellKnown, format, output } = parseArgs(process.argv);
     if (help) {
         console.log(USAGE);
         return;
@@ -71,23 +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));
+        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/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/package.json

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