deeplink-parity 0.3.1 → 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,10 +52,11 @@ 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;
@@ -87,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/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.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": {