deeplink-parity 0.7.0 → 0.8.0

package/README.md

@@ -146,6 +146,7 @@ npx deeplink-parity baseline [path...]         # freeze current findings; fail o
   --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)
+  --fail-on <level>        error (default) · warn to also gate on warnings · never
   --yes                    init only: accept the top suggestion without prompting
   -v, --version            Print the version
   -h, --help               Show this message
@@ -190,7 +191,7 @@ Findings appear as annotations on the run, and counts are available to later ste
 | `well-known` | — | Read from disk instead of the network |
 | `config` | auto | Route config file (see [Route parity](#route-parity)) |
 | `baseline` | auto | Baseline file (see [Start with existing findings](#start-with-existing-findings)) |
-| `fail-on` | `error` | `never` to report without failing the step |
+| `fail-on` | `error` | `warn` to also gate on warnings (route gaps), `never` to report without failing |
 | `version` | pinned | npm version to run |
 
 Outputs: `errors`, `warnings`, `notices`, `domains`, `report` (path to the JSON result).
@@ -219,7 +220,9 @@ npx deeplink-parity baseline ./app-ios ./app-android
 
 That writes `deeplink-parity-baseline.json` — commit it. From then on every check still
 **reports** the known findings, marked `(baselined)`, but only a finding that is not in
-the file fails the run. The file stores a one-line summary per finding, so a reviewer
+the file can fail the run. By default only errors fail; pass `--fail-on warn` to make
+warnings (route gaps, platform domain gaps) gate too — that is what makes freezing
+warnings in a baseline meaningful. The file stores a one-line summary per finding, so a reviewer
 can read what is being tolerated. When a baselined problem gets fixed, the check says
 so; re-run `baseline` to tighten the file.
 

package/dist/cli.js

@@ -51,6 +51,7 @@ function parseArgs(argv) {
     let output;
     let config;
     let baseline;
+    let failOn = 'error';
     // 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++) {
@@ -77,9 +78,27 @@ function parseArgs(argv) {
             config = args[++i];
         else if (arg === '--baseline')
             baseline = args[++i];
-        else if (!arg.startsWith('-'))
+        else if (arg === '--fail-on') {
+            const v = args[++i];
+            if (v !== 'error' && v !== 'warn' && v !== 'never') {
+                console.error(`error: --fail-on must be "error", "warn" or "never", got "${v}"`);
+                process.exit(2);
+            }
+            failOn = v;
+        }
+        else if (arg.startsWith('-')) {
+            // a mistyped flag must not become a scan root or silently drop an option —
+            // --well-knwon once sent a "no egress" CI run out to the real network
+            console.error(`error: unknown flag "${arg}" — see --help`);
+            process.exit(2);
+        }
+        else
             positional.push(arg);
     }
+    if (format !== 'console' && format !== 'github') {
+        console.error(`error: --format must be "console" or "github", got "${format}"`);
+        process.exit(2);
+    }
     const command = positional[0] === 'init' || positional[0] === 'baseline' ? positional[0] : 'check';
     const roots = (command === 'check' ? positional : positional.slice(1)).map((r) => resolve(r));
     return {
@@ -96,6 +115,7 @@ function parseArgs(argv) {
         config,
         baseline,
         format,
+        failOn,
     };
 }
 /**
@@ -173,7 +193,14 @@ async function main() {
             });
         }
     }
-    const nothingFound = result.iosApps.length === 0 && result.androidApps.length === 0 && result.findings.length === 0;
+    // a run that successfully extracted route tables is a legitimate run — before this
+    // guard, a routes-only run failed exactly when every route matched and passed when
+    // there were gaps, inverting success and failure
+    const routesExtracted = Boolean(result.routes?.ios ?? result.routes?.android);
+    const nothingFound = result.iosApps.length === 0 &&
+        result.androidApps.length === 0 &&
+        result.findings.length === 0 &&
+        !routesExtracted;
     if (nothingFound) {
         console.error(`No app configuration declaring deep links was found in ${opts.roots.join(', ')}`);
         console.error('Expected a .entitlements file with applinks:, or an AndroidManifest.xml with intent-filters.');
@@ -214,9 +241,12 @@ async function main() {
             : undefined,
         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,
+            // counts exclude baselined findings, matching the exit-code semantics — a
+            // consumer branching on `error` must agree with whether the run failed
+            error: result.findings.filter((f) => f.severity === 'error' && !f.baselined).length,
+            warn: result.findings.filter((f) => f.severity === 'warn' && !f.baselined).length,
+            info: result.findings.filter((f) => f.severity === 'info' && !f.baselined).length,
+            baselined: result.findings.filter((f) => f.baselined).length,
         },
         findings: result.findings,
     };
@@ -242,7 +272,7 @@ async function main() {
             printGithubAnnotations(result.findings);
         printReport(result.findings, result.domains, { version: pkg.version, routesLine });
     }
-    process.exit(exitCodeFor(result.findings));
+    process.exit(exitCodeFor(result.findings, opts.failOn));
 }
 main().catch((err) => {
     console.error(err instanceof Error ? err.message : err);

package/dist/discover/android.js

@@ -55,7 +55,7 @@ function applicationIds(gradleSources) {
 export async function discoverAndroid(root) {
     const manifests = (await walk(root, (n) => n === 'AndroidManifest.xml')).filter(
     // androidTest/debug manifests rarely declare shipping deep links
-    (p) => !/src\/(androidTest|test)\//.test(p));
+    (p) => !/src[\/\\](androidTest|test)[\/\\]/.test(p));
     if (manifests.length === 0)
         return [];
     const index = emptyIndex();

package/dist/discover/ios.js

@@ -69,9 +69,10 @@ function matchSigning(path, signing) {
     return best;
 }
 export async function discoverIos(root) {
+    const findings = [];
     const entitlementFiles = await walk(root, (n) => n.endsWith('.entitlements'));
     if (entitlementFiles.length === 0)
-        return [];
+        return { apps: [], findings };
     const pbxprojPaths = await walk(root, (n) => n === 'project.pbxproj');
     const signing = new Map();
     for (const path of pbxprojPaths) {
@@ -86,7 +87,15 @@ export async function discoverIos(root) {
         try {
             parsed = plist.parse(await readFile(path, 'utf8'));
         }
-        catch {
+        catch (err) {
+            // a file that fails to parse would read as "no declaration" — silent narrowing
+            findings.push({
+                severity: 'warn',
+                rule: 'entitlements-unreadable',
+                message: `Could not parse ${path} — ${err instanceof Error ? err.message : String(err)}`,
+                detail: 'If this file declares applinks:, its domains were NOT checked this run.',
+                source: path,
+            });
             continue;
         }
         const dict = parsed;
@@ -104,5 +113,5 @@ export async function discoverIos(root) {
             teamId: target.teamId,
         });
     }
-    return apps;
+    return { apps, findings };
 }

package/dist/fetch/wellKnown.js

@@ -81,8 +81,12 @@ export function localSource(dir) {
                 body: await readFile(path, 'utf8'),
             };
         }
-        catch {
-            return { url: path, ok: false, status: 404, redirected: false };
+        catch (err) {
+            // only a missing file is a 404 — a permission error reported as 404 misleads
+            if (err.code === 'ENOENT') {
+                return { url: path, ok: false, status: 404, redirected: false };
+            }
+            return { url: path, ok: false, redirected: false, error: err instanceof Error ? err.message : String(err) };
         }
     };
     return {

package/dist/report/console.js

@@ -23,26 +23,45 @@ export function printReport(findings, checkedDomains, meta) {
         console.log();
         return;
     }
+    const SHOW_PER_RULE = 20;
     for (const severity of ORDER) {
-        for (const f of findings.filter((x) => x.severity === severity)) {
-            const head = paint(LABEL[severity], COLOR[severity]);
-            // Not every finding is tied to a domain — fall back to the rule id so the line is never blank
-            const subject = f.domain ? paint(f.domain, BOLD) : paint(f.rule, DIM);
-            const known = f.baselined ? ` ${paint('(baselined)', DIM)}` : '';
-            console.log(`${head}  ${subject}${known}`);
-            console.log(`       ${f.message}`);
-            if (f.detail)
-                console.log(`       ${paint(f.detail, DIM)}`);
-            if (f.source)
-                console.log(`       ${paint(f.source, DIM)}`);
-            console.log();
+        const ofSeverity = findings.filter((x) => x.severity === severity);
+        const byRule = new Map();
+        for (const f of ofSeverity) {
+            byRule.set(f.rule, [...(byRule.get(f.rule) ?? []), f]);
+        }
+        for (const [rule, group] of byRule) {
+            for (const f of group.slice(0, SHOW_PER_RULE)) {
+                const head = paint(LABEL[severity], COLOR[severity]);
+                // Not every finding is tied to a domain — fall back to the rule id so the line is never blank
+                const subject = f.domain ? paint(f.domain, BOLD) : paint(f.rule, DIM);
+                const known = f.baselined ? ` ${paint('(baselined)', DIM)}` : '';
+                console.log(`${head}  ${subject}${known}`);
+                console.log(`       ${f.message}`);
+                if (f.detail)
+                    console.log(`       ${paint(f.detail, DIM)}`);
+                if (f.source)
+                    console.log(`       ${paint(f.source, DIM)}`);
+                console.log();
+            }
+            if (group.length > SHOW_PER_RULE) {
+                console.log(paint(`       … ${group.length - SHOW_PER_RULE} more ${rule} finding(s) — see --json or --output for all`, DIM));
+                console.log();
+            }
         }
     }
     const counts = ORDER.map((s) => `${findings.filter((f) => f.severity === s).length} ${s}`);
     console.log(counts.join(', '));
     console.log();
 }
-/** A baselined error is a known problem being tracked — it must not fail the run. */
-export function exitCodeFor(findings) {
-    return findings.some((f) => f.severity === 'error' && !f.baselined) ? 1 : 0;
+/**
+ * A baselined finding is a known problem being tracked — it must not fail the run.
+ * --fail-on warn makes route parity (all warn) an actual CI gate; without it, freezing
+ * warns in a baseline had no effect beyond a label.
+ */
+export function exitCodeFor(findings, failOn = 'error') {
+    if (failOn === 'never')
+        return 0;
+    const failing = (f) => !f.baselined && (f.severity === 'error' || (failOn === 'warn' && f.severity === 'warn'));
+    return findings.some(failing) ? 1 : 0;
 }

package/dist/report/github.js

@@ -16,8 +16,17 @@ function escapeProperty(value) {
  * changed lines when a finding points at a file in the repository.
  * https://docs.github.com/actions/reference/workflow-commands-for-github-actions
  */
+const ANNOTATIONS_PER_RULE = 10;
 export function printGithubAnnotations(findings) {
+    const emitted = new Map();
+    const truncated = new Map();
     for (const f of findings) {
+        const count = emitted.get(f.rule) ?? 0;
+        if (count >= ANNOTATIONS_PER_RULE) {
+            truncated.set(f.rule, (truncated.get(f.rule) ?? 0) + 1);
+            continue;
+        }
+        emitted.set(f.rule, count + 1);
         // a known finding stays visible but must not paint the run red
         const level = f.baselined ? 'notice' : LEVEL[f.severity];
         const props = [`title=${escapeProperty(`deeplink-parity ${f.rule}`)}`];
@@ -32,4 +41,7 @@ export function printGithubAnnotations(findings) {
             .join(' — ');
         console.log(`::${level} ${props.join(',')}::${escapeData(body)}`);
     }
+    for (const [rule, count] of truncated) {
+        console.log(`::notice title=${escapeProperty(`deeplink-parity ${rule}`)}::${escapeData(`${count} more ${rule} finding(s) not annotated — see the JSON report for all`)}`);
+    }
 }

package/dist/resolve/androidResources.js

@@ -30,8 +30,16 @@ export async function indexResValues(paths, index) {
             const args = m[1];
             if (!/["']string["']/.test(args))
                 continue;
-            const name = /name\s*=\s*["']([^"']+)["']/.exec(args)?.[1];
-            const value = /value\s*=\s*([\s\S]+?)\s*$/.exec(args)?.[1];
+            let name = /name\s*=\s*["']([^"']+)["']/.exec(args)?.[1];
+            let value = name ? /value\s*=\s*([\s\S]+?)\s*$/.exec(args)?.[1] : undefined;
+            if (!name) {
+                // parenthesised positional form — resValue("string", "host", "example.com")
+                const positional = /^\s*["']string["']\s*,\s*["']([^"']+)["']\s*,\s*([\s\S]+?)\s*$/.exec(args);
+                if (positional) {
+                    name = positional[1];
+                    value = positional[2];
+                }
+            }
             if (!name || !value)
                 continue;
             const list = index.resValues.get(name) ?? [];
@@ -69,8 +77,14 @@ export async function indexProperties(paths, index) {
  */
 function resolveGradleExpression(expr, index) {
     const literal = /^(["'])([^"']*)\1(?:\s+as\s+\w+)?$/.exec(expr.trim());
-    if (literal)
+    if (literal) {
+        // a double-quoted string containing $ is interpolated (Groovy GString, Kotlin
+        // template) — treating "${envHost}.example.com" as a literal host once sent a
+        // fetch to a domain that does not exist and misreported it as unreachable
+        if (literal[1] === '"' && literal[2].includes('$'))
+            return undefined;
         return literal[2];
+    }
     const lookup = /\[\s*["']([^"']+)["']\s*\]/.exec(expr) ?? /getProperty\(\s*["']([^"']+)["']\s*\)/.exec(expr);
     if (lookup)
         return index.properties.get(lookup[1]);

package/dist/routes/check.js

@@ -1,20 +1,10 @@
-/** Above this many gaps per direction, one grouped finding replaces per-path noise. */
-const GROUP_THRESHOLD = 20;
 const DYNAMIC_NOTE = 'Routes handled dynamically (prefix or path-component matching) never appear in a route table — confirm before acting.';
 function gapFindings(present, absent, gaps) {
     const presentName = present.platform === 'ios' ? 'iOS' : 'Android';
     const absentName = absent.platform === 'ios' ? 'iOS' : 'Android';
-    if (gaps.length > GROUP_THRESHOLD) {
-        return [
-            {
-                severity: 'warn',
-                rule: 'route-gap',
-                message: `${gaps.length} routes are in the ${presentName} route table but not ${absentName}'s`,
-                detail: `${gaps.join(', ')} · ${DYNAMIC_NOTE}`,
-                source: present.files[0],
-            },
-        ];
-    }
+    // Always one finding per path: a grouped finding keyed its baseline identity on a
+    // message containing the gap COUNT, so 21→22 gaps refired everything. The reporters
+    // collapse long runs visually instead.
     return gaps.map((path) => ({
         severity: 'warn',
         rule: 'route-gap',

package/dist/run.js

@@ -22,9 +22,9 @@ async function runRouteChecks(routes, roots, findings) {
 }
 export async function run({ roots, source, sha256, routes, onDiscovered, }) {
     const discovered = await Promise.all(roots.map(async (root) => Promise.all([discoverIos(root), discoverAndroid(root)])));
-    const iosApps = discovered.flatMap(([ios]) => ios);
+    const iosApps = discovered.flatMap(([ios]) => ios.apps);
     const androidApps = discovered.flatMap(([, android]) => android);
-    const findings = [];
+    const findings = discovered.flatMap(([ios]) => ios.findings);
     // an Expo checkout has no native project committed; say so rather than report nothing
     if (iosApps.length === 0 && androidApps.length === 0) {
         for (const root of roots)
@@ -36,39 +36,76 @@ export async function run({ roots, source, sha256, routes, onDiscovered, }) {
         ...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));
-        fresh.forEach((d) => ios.domains.add(d));
-        const wildcards = fresh.filter(isWildcardDomain);
-        wildcards.forEach((d) => findings.push(wildcardFinding(d, app.entitlementsPath)));
-        const pending = fresh.filter((d) => !isWildcardDomain(d));
-        const results = await mapLimit(pending, FETCH_CONCURRENCY, (d) => source.aasa(d));
-        pending.forEach((domain, i) => {
-            const { findings: domainFindings, aasa } = checkIosDomain(app, domain, results[i]);
-            findings.push(...domainFindings);
-            if (aasa)
-                ios.paths.set(domain, aasaPaths(aasa));
-        });
+    // The same domain is often declared by several targets (app + widget, prod + dev
+    // flavours). Fetch each domain once, but evaluate the rules for every (app, domain)
+    // pair — a second target missing from the AASA is exactly the false clean this tool
+    // exists to prevent. Domain-level findings that come out identical are deduped below.
+    {
+        const allDomains = [...new Set(iosApps.flatMap((a) => a.domains))];
+        for (const domain of allDomains.filter(isWildcardDomain)) {
+            const declaringApp = iosApps.find((a) => a.domains.includes(domain));
+            if (declaringApp)
+                findings.push(wildcardFinding(domain, declaringApp.entitlementsPath));
+            ios.domains.add(domain);
+        }
+        const fetchable = allDomains.filter((d) => !isWildcardDomain(d));
+        const results = await mapLimit(fetchable, FETCH_CONCURRENCY, (d) => source.aasa(d));
+        const fetched = new Map(fetchable.map((d, i) => [d, results[i]]));
+        for (const app of iosApps) {
+            for (const domain of app.domains) {
+                const res = fetched.get(domain);
+                if (!res)
+                    continue;
+                ios.domains.add(domain);
+                const { findings: domainFindings, aasa } = checkIosDomain(app, domain, res);
+                findings.push(...domainFindings);
+                if (aasa && !ios.paths.has(domain))
+                    ios.paths.set(domain, aasaPaths(aasa));
+            }
+        }
     }
-    for (const app of androidApps) {
-        findings.push(...checkAndroidUnresolved(app));
-        const fresh = app.hosts.filter((h) => !android.domains.has(h.host));
-        fresh.forEach((h) => {
+    {
+        for (const app of androidApps)
+            findings.push(...checkAndroidUnresolved(app));
+        const entries = androidApps.flatMap((app) => app.hosts.map((h) => ({ app, h })));
+        const seenWildcards = new Set();
+        for (const { app, h } of entries) {
+            if (!isWildcardDomain(h.host) || seenWildcards.has(h.host))
+                continue;
+            seenWildcards.add(h.host);
             android.domains.add(h.host);
-            if (h.paths.length > 0)
-                android.paths.set(h.host, h.paths);
-        });
-        fresh
-            .filter((h) => isWildcardDomain(h.host))
-            .forEach((h) => findings.push(wildcardFinding(h.host, app.manifestPath)));
-        const pending = fresh.filter((h) => !isWildcardDomain(h.host));
-        // an unverified host is never checked by the system, so there is nothing to fetch
-        const results = await mapLimit(pending, FETCH_CONCURRENCY, (h) => h.autoVerify ? source.assetlinks(h.host) : Promise.resolve(null));
-        pending.forEach((entry, i) => {
-            const res = results[i] ?? { url: '', ok: false, redirected: false };
-            findings.push(...checkAndroidHost(app, entry, res, { sha256 }));
+            findings.push(wildcardFinding(h.host, app.manifestPath));
+        }
+        // an unverified host is never checked by the system, so there is nothing to fetch —
+        // but fetch once per host if ANY declaring app verifies it, whichever app came first
+        const checkable = entries.filter(({ h }) => !isWildcardDomain(h.host));
+        const hostsToFetch = [
+            ...new Set(checkable.filter(({ h }) => h.autoVerify).map(({ h }) => h.host)),
+        ];
+        const results = await mapLimit(hostsToFetch, FETCH_CONCURRENCY, (host) => source.assetlinks(host));
+        const fetched = new Map(hostsToFetch.map((host, i) => [host, results[i]]));
+        for (const { app, h } of checkable) {
+            android.domains.add(h.host);
+            if (h.paths.length > 0) {
+                // every declaring app's paths count toward the cross-platform comparison
+                android.paths.set(h.host, [...new Set([...(android.paths.get(h.host) ?? []), ...h.paths])]);
+            }
+            const res = (h.autoVerify ? fetched.get(h.host) : null) ?? { url: '', ok: false, redirected: false };
+            findings.push(...checkAndroidHost(app, h, res, { sha256 }));
+        }
+    }
+    // per-(app, domain) evaluation makes domain-level findings repeat verbatim — keep one
+    {
+        const seen = new Set();
+        const deduped = findings.filter((f) => {
+            const key = [f.severity, f.rule, f.domain ?? '', f.message, f.source ?? ''].join('\u0000');
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
         });
+        findings.length = 0;
+        findings.push(...deduped);
     }
     findings.push(...checkCrossPlatform(ios, android));
     const routeTables = routes ? await runRouteChecks(routes, roots, findings) : undefined;

package/package.json

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