deeplink-parity 0.5.0 → 0.6.0

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,54 @@ 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)
+- [Route parity](#route-parity)
+- [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.
@@ -77,11 +124,18 @@ No configuration file. Domains are discovered from your app, then the matching w
 ## Usage
 
 ```bash
-npx deeplink-parity [path...] [options]
+npx deeplink-parity [path...] [options]        # check (default)
+npx deeplink-parity init [path...]             # interactive setup for route comparison
 
   --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
+  --config <file>          Route config (default: deeplink-parity.yml in cwd or a root)
+  --print-routes           Print the extracted route tables before the report
+  --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)
+  --yes                    init only: accept the top suggestion without prompting
+  -h, --help               Show this message
 ```
 
 Pass one path per checkout. A monorepo holding both platforms works as a single path,
@@ -121,6 +175,7 @@ Findings appear as annotations on the run, and counts are available to later ste
 | `paths` | `.` | Checkout paths, whitespace separated |
 | `sha256` | — | Android signing fingerprint |
 | `well-known` | — | Read from disk instead of the network |
+| `config` | auto | Route config file (see [Route parity](#route-parity)) |
 | `fail-on` | `error` | `never` to report without failing the step |
 | `version` | pinned | npm version to run |
 
@@ -139,7 +194,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:
 
@@ -152,14 +207,73 @@ 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>
 
+## Route parity
+
+Domains are only half the story. The other half is the screen behind the link: a route
+registered on Android but never on iOS means `myapp://link/events` navigates on one
+platform and goes nowhere on the other — and the person sending that link has no way
+to know.
+
+Route tables live in app code with no standard location, so this check is **opt-in via
+one config file**. Run the interactive setup once:
+
+```bash
+npx deeplink-parity init ./my-app-ios ./my-app-android
+```
+
+It scans for likely route-table files, lets you pick one per platform (or type a path
+yourself), recognises the table's shape, previews what it extracts, and writes
+`deeplink-parity.yml`:
+
+```yaml
+routes:
+  ios:
+    file: App/Routing/DeepLinkRoutes.swift     # relative to whichever root it lives under
+    match: 'case \w+ = "(/[a-z0-9/_-]+)"'      # capture group 1 = the path
+  android:
+    file: app/src/main/java/…/DeepLinks.kt
+    match: '[A-Z_]+\("(/[a-z0-9/_-]+)"\)'
+```
+
+Commit it. From then on every check — CLI and Action alike — also diffs the two route
+tables and reports the paths one platform has and the other does not. Verify the
+extraction any time with `--print-routes`.
+
+Accuracy guards, in keeping with the rest of the tool:
+
+- A regex that matches nothing is an **error**, never a clean pass
+- If only one platform extracts, no gaps are reported — a broken table is not a diff
+- Routes handled dynamically (prefix or component matching) never appear in a table;
+  gap findings carry that caveat
+
+### What the tool touches
+
+The **check never writes to the repositories it scans** — it reads files and GETs two
+public well-known files per domain, nothing else. `init` writes exactly one file,
+`deeplink-parity.yml`, in your working directory, after printing its content and asking.
+
 ## Native, Flutter and React Native
 
 Whatever the app is written in, deep links are declared in the same two native files and

package/dist/cli.js

@@ -4,12 +4,15 @@ 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 { findConfig, loadRoutesConfig } from './routes/config.js';
+import { runInit } from './routes/init.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.
 
 Usage
-  deeplink-parity [path...] [options]
+  deeplink-parity [path...] [options]        check (default)
+  deeplink-parity init [path...]             interactive setup for route comparison
 
   Pass one path per checkout. iOS and Android usually live in separate
   repositories, and comparing them is the point:
@@ -19,19 +22,29 @@ 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
+  --config <file>          Route config (default: deeplink-parity.yml in cwd or a root)
+  --print-routes           Print the extracted route tables before the report
   --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)
+  --yes                    init only: accept the top suggestion without prompting
   -h, --help               Show this message
+
+The check reads the repositories and GETs two public well-known files per domain —
+it never writes to the repositories it scans. init writes exactly one file
+(deeplink-parity.yml), shows the content first, and asks.
 `;
 function parseArgs(argv) {
     const args = argv.slice(2);
-    const roots = [];
+    const positional = [];
     let json = false;
     let help = false;
+    let printRoutes = false;
+    let yes = false;
     let sha256;
     let wellKnown;
     let output;
+    let config;
     // 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++) {
@@ -40,6 +53,10 @@ function parseArgs(argv) {
             json = true;
         else if (arg === '-h' || arg === '--help')
             help = true;
+        else if (arg === '--print-routes')
+            printRoutes = true;
+        else if (arg === '--yes')
+            yes = true;
         else if (arg === '--sha256')
             sha256 = args[++i];
         else if (arg === '--well-known')
@@ -48,42 +65,67 @@ function parseArgs(argv) {
             format = args[++i];
         else if (arg === '--output')
             output = args[++i];
+        else if (arg === '--config')
+            config = args[++i];
         else if (!arg.startsWith('-'))
-            roots.push(arg);
+            positional.push(arg);
     }
+    const command = positional[0] === 'init' ? 'init' : 'check';
+    const roots = (command === 'init' ? positional.slice(1) : positional).map((r) => resolve(r));
     return {
-        roots: (roots.length ? roots : ['.']).map((r) => resolve(r)),
+        command,
+        roots: roots.length ? roots : [resolve('.')],
         json,
         help,
+        printRoutes,
+        yes,
         sha256,
         wellKnown,
-        format,
         output,
+        config,
+        format,
     };
 }
 async function main() {
-    const { roots, json, help, sha256, wellKnown, format, output } = parseArgs(process.argv);
-    if (help) {
+    const opts = parseArgs(process.argv);
+    if (opts.help) {
         console.log(USAGE);
         return;
     }
-    const source = wellKnown ? localSource(resolve(wellKnown)) : networkSource();
+    if (opts.command === 'init') {
+        process.exit(await runInit(opts.roots, opts.yes));
+    }
+    const configPath = await findConfig(opts.config, opts.roots);
+    const routes = configPath ? await loadRoutesConfig(configPath) : undefined;
+    const source = opts.wellKnown ? localSource(resolve(opts.wellKnown)) : networkSource();
     const result = await run({
-        roots,
+        roots: opts.roots,
         source,
-        sha256,
+        sha256: opts.sha256,
+        routes,
         onDiscovered: (count) => {
             // some apps declare a domain per country; say so before spending minutes on it
-            if (!wellKnown && count > 50) {
+            if (!opts.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(', ')}`);
+    const nothingFound = result.iosApps.length === 0 && result.androidApps.length === 0 && result.findings.length === 0;
+    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.');
         process.exit(2);
     }
+    if (opts.printRoutes && result.routes) {
+        for (const table of [result.routes.ios, result.routes.android]) {
+            if (!table)
+                continue;
+            console.log(`\n${table.platform === 'ios' ? 'iOS' : 'Android'} routes (${table.paths.length}) — ${table.files.join(', ')}`);
+            for (const path of table.paths)
+                console.log(`  ${path}`);
+        }
+        console.log();
+    }
     const payload = {
         ios: result.iosApps.map((a) => ({
             entitlements: a.entitlementsPath,
@@ -96,6 +138,14 @@ async function main() {
             packageIds: a.packageIds,
             hosts: a.hosts.map((h) => h.host),
         })),
+        routes: result.routes
+            ? {
+                ios: result.routes.ios ? { files: result.routes.ios.files, paths: result.routes.ios.paths } : undefined,
+                android: result.routes.android
+                    ? { files: result.routes.android.files, paths: result.routes.android.paths }
+                    : undefined,
+            }
+            : undefined,
         summary: {
             domains: result.domains.length,
             error: result.findings.filter((f) => f.severity === 'error').length,
@@ -106,19 +156,19 @@ async function main() {
     };
     // 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) {
+    if (opts.output)
+        await writeFile(opts.output, `${JSON.stringify(payload, null, 2)}\n`);
+    if (opts.json) {
         console.log(JSON.stringify(payload, null, 2));
     }
     else {
-        if (format === 'github')
+        if (opts.format === 'github')
             printGithubAnnotations(result.findings);
         printReport(result.findings, result.domains);
     }
     process.exit(exitCodeFor(result.findings));
 }
 main().catch((err) => {
-    console.error(err);
+    console.error(err instanceof Error ? err.message : err);
     process.exit(2);
 });

package/dist/discover/walk.js

@@ -19,6 +19,7 @@ const SKIP_DIRS = new Set([
     '.build',
     '.gradle',
     '.idea',
+    '.claude',
 ]);
 /**
  * Depth-first file scan that skips dependency and build output directories.

package/dist/routes/candidates.js

@@ -0,0 +1,68 @@
+import { readFile, stat } from 'node:fs/promises';
+import { walk } from '../discover/walk.js';
+const PATH_STRING = /"\/[a-z0-9][a-z0-9/_-]*"/g;
+const NAME_HINT = /deeplink|deep-link|route|link|configure|navigat/i;
+// Retrofit / Moya files are full of path strings that are API endpoints, not routes
+const API_MARKER = /@GET|@POST|@PUT|@DELETE|@PATCH\(|TargetType|baseURL|HttpUrl/;
+const SKIP_PATH = /\/(test|tests|androidTest|mock|mocks|__tests__|Pods|\.claude)\//i;
+const MAX_FILE_SIZE = 1_000_000;
+/**
+ * Rank likely route-table files: many path-like strings, a routing hint in the name,
+ * and not an API client. Scoring is deterministic — the user confirms the pick, so
+ * precision comes from them, not from the heuristic.
+ */
+export async function findCandidates(roots) {
+    const sources = [];
+    for (const root of roots) {
+        sources.push(...(await walk(root, (n) => n.endsWith('.swift') || n.endsWith('.kt') || n.endsWith('.java'))));
+    }
+    const candidates = [];
+    for (const file of sources) {
+        if (SKIP_PATH.test(file))
+            continue;
+        try {
+            if ((await stat(file)).size > MAX_FILE_SIZE)
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const content = await readFile(file, 'utf8');
+        const pathStrings = (content.match(PATH_STRING) ?? []).length;
+        if (pathStrings < 3)
+            continue;
+        let score = pathStrings;
+        if (NAME_HINT.test(file))
+            score += 30;
+        if (API_MARKER.test(content))
+            score -= 40;
+        candidates.push({
+            file,
+            platform: file.endsWith('.swift') ? 'ios' : 'android',
+            pathStrings,
+            score,
+        });
+    }
+    return candidates.sort((a, b) => b.score - a.score);
+}
+/** Known table shapes, most specific first. Tried against the chosen file. */
+const SHAPES = [
+    { name: 'Swift enum rawValue', pattern: String.raw `case \w+\s*=\s*"(\/[^"\s]+)"` },
+    { name: 'Swift path property', pattern: String.raw `let path\s*=\s*"(\/[^"\s]+)"` },
+    { name: 'Kotlin enum argument', pattern: String.raw `[A-Z][A-Z_0-9]*\(\s*"(\/[^"\s]+)"` },
+    { name: 'when/switch branch', pattern: String.raw `"(\/[^"\s]+)"\s*->` },
+    { name: 'any path string', pattern: String.raw `"(\/[a-z0-9][a-z0-9\/_-]*)"` },
+];
+export async function suggestRegex(file) {
+    const content = await readFile(file, 'utf8');
+    const suggestions = [];
+    for (const shape of SHAPES) {
+        const paths = [
+            ...new Set([...content.matchAll(new RegExp(shape.pattern, 'g'))].map((m) => m[1])),
+        ].sort();
+        if (paths.length > 0)
+            suggestions.push({ name: shape.name, pattern: shape.pattern, paths });
+    }
+    // best extraction first; ties keep the more specific shape ahead
+    return suggestions.sort((a, b) => b.paths.length - a.paths.length);
+}

package/dist/routes/check.js

@@ -0,0 +1,51 @@
+/** 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],
+            },
+        ];
+    }
+    return gaps.map((path) => ({
+        severity: 'warn',
+        rule: 'route-gap',
+        message: `${path} is in the ${presentName} route table but not ${absentName}'s`,
+        detail: `A ${path} link navigates on ${presentName} and goes nowhere on ${absentName}. ${DYNAMIC_NOTE}`,
+        source: present.files[0],
+    }));
+}
+/**
+ * The comparison only runs when both tables extracted successfully — diffing a full
+ * table against a failed or missing one would manufacture gaps that do not exist.
+ */
+export function compareRoutes(ios, android) {
+    if (!ios && !android)
+        return [];
+    if (!ios || !android) {
+        const present = (ios ?? android);
+        return [
+            {
+                severity: 'info',
+                rule: 'route-single-platform',
+                message: `Routes are configured for ${present.platform === 'ios' ? 'iOS' : 'Android'} only`,
+                detail: `${present.paths.length} route(s) extracted. Configure both platforms to compare them.`,
+                source: present.files[0],
+            },
+        ];
+    }
+    const iosSet = new Set(ios.paths);
+    const androidSet = new Set(android.paths);
+    return [
+        ...gapFindings(ios, android, ios.paths.filter((p) => !androidSet.has(p))),
+        ...gapFindings(android, ios, android.paths.filter((p) => !iosSet.has(p))),
+    ];
+}

package/dist/routes/config.js

@@ -0,0 +1,56 @@
+import { access, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { load } from 'js-yaml';
+const CONFIG_NAMES = ['deeplink-parity.yml', 'deeplink-parity.yaml'];
+/**
+ * An explicit --config always wins. Otherwise the file is looked up in the working
+ * directory first, then in each scanned root, so a monorepo can keep it at its root
+ * and a two-repo setup can keep it in either checkout.
+ */
+export async function findConfig(explicit, roots) {
+    if (explicit)
+        return resolve(explicit);
+    for (const dir of [process.cwd(), ...roots]) {
+        for (const name of CONFIG_NAMES) {
+            const candidate = join(dir, name);
+            try {
+                await access(candidate);
+                return candidate;
+            }
+            catch {
+                // keep looking
+            }
+        }
+    }
+    return undefined;
+}
+/** Throws with a plain message on a malformed config — that is a setup error, not a finding. */
+export async function loadRoutesConfig(path) {
+    const raw = load(await readFile(path, 'utf8'));
+    const routes = raw?.['routes'];
+    if (!routes || typeof routes !== 'object')
+        return {};
+    const normalize = (key) => {
+        const entry = routes[key];
+        if (!entry)
+            return undefined;
+        const files = Array.isArray(entry['files'])
+            ? entry['files'].filter((f) => typeof f === 'string')
+            : typeof entry['file'] === 'string'
+                ? [entry['file']]
+                : [];
+        const match = entry['match'];
+        if (files.length === 0 || typeof match !== 'string') {
+            throw new Error(`routes.${key} needs "file" (or "files") and "match" in ${path}`);
+        }
+        try {
+            // validate early so a bad pattern fails the run, not silently matches nothing
+            new RegExp(match, 'g');
+        }
+        catch (err) {
+            throw new Error(`routes.${key}.match is not a valid regex: ${err.message}`);
+        }
+        return { files, match };
+    };
+    return { ios: normalize('ios'), android: normalize('android') };
+}

package/dist/routes/extract.js

@@ -0,0 +1,76 @@
+import { access, readFile } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { displayPath } from '../discover/walk.js';
+/**
+ * A config path is relative to whichever scanned root it exists under, so the same
+ * file works locally (`~/ios ~/android`) and in CI (`ios/ android/`). Existing in
+ * more than one root is ambiguous and reported rather than guessed at.
+ */
+async function resolveInRoots(file, roots) {
+    if (isAbsolute(file)) {
+        try {
+            await access(file);
+            return [file];
+        }
+        catch {
+            return [];
+        }
+    }
+    const hits = [];
+    for (const root of roots) {
+        const candidate = join(root, file);
+        try {
+            await access(candidate);
+            hits.push(candidate);
+        }
+        catch {
+            // not under this root
+        }
+    }
+    return hits;
+}
+export async function extractRoutes(platform, config, roots) {
+    const findings = [];
+    const files = [];
+    const paths = new Set();
+    for (const file of config.files) {
+        const hits = await resolveInRoots(file, roots);
+        if (hits.length === 0) {
+            findings.push({
+                severity: 'error',
+                rule: 'routes-file-missing',
+                message: `Route file not found under any scanned root: ${file}`,
+                detail: 'Fix the path in deeplink-parity.yml, or re-run `deeplink-parity init`',
+            });
+            continue;
+        }
+        if (hits.length > 1) {
+            findings.push({
+                severity: 'error',
+                rule: 'routes-file-ambiguous',
+                message: `Route file exists under more than one root: ${file}`,
+                detail: hits.map((h) => displayPath(h)).join(' · '),
+            });
+            continue;
+        }
+        const content = await readFile(hits[0], 'utf8');
+        files.push(displayPath(hits[0]));
+        for (const m of content.matchAll(new RegExp(config.match, 'g'))) {
+            paths.add(m[1] ?? m[0]);
+        }
+    }
+    if (files.length > 0 && paths.size === 0) {
+        // matching nothing is a broken config, never a clean pass
+        findings.push({
+            severity: 'error',
+            rule: 'routes-extraction-empty',
+            message: `The ${platform} route regex matched nothing`,
+            detail: `Pattern: ${config.match} · Files: ${files.join(', ')}. Verify with --print-routes.`,
+            source: files[0],
+        });
+        return { findings };
+    }
+    if (files.length === 0)
+        return { findings };
+    return { routes: { platform, files, paths: [...paths].sort() }, findings };
+}

package/dist/routes/init.js

@@ -0,0 +1,118 @@
+import { access, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { dump } from 'js-yaml';
+import { findCandidates, suggestRegex } from './candidates.js';
+const PREVIEW = 8;
+/** The config records paths relative to the root a file lives under, never absolute. */
+function rootRelative(file, roots) {
+    for (const root of roots) {
+        const rel = relative(root, file);
+        if (!rel.startsWith('..'))
+            return rel;
+    }
+    return file;
+}
+async function pickFile(rl, platform, candidates, yes) {
+    const top = candidates.filter((c) => c.platform === platform).slice(0, 5);
+    if (top.length === 0) {
+        if (yes)
+            return undefined;
+        const manual = (await rl.question(`No ${platform} route-file candidates found. Enter a path, or leave blank to skip: `)).trim();
+        return manual || undefined;
+    }
+    if (yes)
+        return top[0].file;
+    console.log(`\n${platform === 'ios' ? 'iOS' : 'Android'} route file candidates:`);
+    top.forEach((c, i) => console.log(`  ${i + 1}. ${c.file}  (${c.pathStrings} path strings)`));
+    console.log(`  m. enter a path manually`);
+    console.log(`  s. skip ${platform}`);
+    const answer = (await rl.question('> ')).trim().toLowerCase();
+    if (answer === 's' || answer === '')
+        return undefined;
+    if (answer === 'm') {
+        const manual = (await rl.question('path: ')).trim();
+        return manual || undefined;
+    }
+    const index = Number.parseInt(answer, 10);
+    return Number.isInteger(index) && index >= 1 && index <= top.length ? top[index - 1].file : undefined;
+}
+async function pickRegex(rl, file, yes) {
+    const suggestions = await suggestRegex(file);
+    if (suggestions.length > 0) {
+        const best = suggestions[0];
+        const preview = best.paths.slice(0, PREVIEW).join(', ');
+        const more = best.paths.length > PREVIEW ? ` … +${best.paths.length - PREVIEW} more` : '';
+        console.log(`\n  Recognised shape: ${best.name}`);
+        console.log(`  Extracts ${best.paths.length} path(s): ${preview}${more}`);
+        if (yes)
+            return best.pattern;
+        const answer = (await rl.question('  Use this? (Y = yes / r = enter my own regex): ')).trim().toLowerCase();
+        if (answer === '' || answer === 'y')
+            return best.pattern;
+    }
+    else {
+        console.log('\n  No known shape matched this file.');
+        if (yes)
+            return undefined;
+    }
+    const custom = (await rl.question('  Regex (capture group 1 = path), blank to skip: ')).trim();
+    return custom || undefined;
+}
+/**
+ * The only command that writes anything, and it writes exactly one file — the config —
+ * after printing its full content and asking. The scanned repositories are never touched.
+ */
+export async function runInit(roots, yes) {
+    console.log(`Scanning ${roots.length} root(s) for route tables…`);
+    const candidates = await findCandidates(roots);
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const picks = {};
+        for (const platform of ['ios', 'android']) {
+            const file = await pickFile(rl, platform, candidates, yes);
+            if (!file)
+                continue;
+            const match = await pickRegex(rl, file, yes);
+            if (!match)
+                continue;
+            picks[platform] = { file: rootRelative(file, roots), match };
+        }
+        if (!picks.ios && !picks.android) {
+            console.log('\nNothing selected — no config written.');
+            return 2;
+        }
+        const yaml = dump({
+            routes: Object.fromEntries(Object.entries(picks).map(([platform, pick]) => [platform, pick])),
+        });
+        const target = join(process.cwd(), 'deeplink-parity.yml');
+        console.log(`\nThis will be written to ${target}:\n`);
+        console.log(yaml.replace(/^/gm, '  '));
+        try {
+            await access(target);
+            const answer = yes
+                ? 'y'
+                : (await rl.question('deeplink-parity.yml already exists. Overwrite? (y/N): ')).trim().toLowerCase();
+            if (answer !== 'y') {
+                console.log('Left the existing file alone.');
+                return 2;
+            }
+        }
+        catch {
+            if (!yes) {
+                const answer = (await rl.question('Write it? (Y/n): ')).trim().toLowerCase();
+                if (answer === 'n') {
+                    console.log('Nothing written.');
+                    return 2;
+                }
+            }
+        }
+        await writeFile(target, yaml);
+        console.log(`Wrote ${target} — commit it, then run the check as usual.`);
+        console.log('The check itself never writes to the repositories it scans.');
+        return 0;
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/run.js

@@ -6,10 +6,21 @@ import { checkAndroidHost, checkAndroidUnresolved } from './rules/android.js';
 import { checkCrossPlatform } from './rules/cross.js';
 import { aasaPaths, checkIosDomain } from './rules/ios.js';
 import { isWildcardDomain, wildcardFinding } from './rules/wildcard.js';
+import { compareRoutes } from './routes/check.js';
+import { extractRoutes } from './routes/extract.js';
 function emptyView() {
     return { domains: new Set(), paths: new Map() };
 }
-export async function run({ roots, source, sha256, onDiscovered }) {
+async function runRouteChecks(routes, roots, findings) {
+    const [ios, android] = await Promise.all([
+        routes.ios ? extractRoutes('ios', routes.ios, roots) : undefined,
+        routes.android ? extractRoutes('android', routes.android, roots) : undefined,
+    ]);
+    findings.push(...(ios?.findings ?? []), ...(android?.findings ?? []));
+    findings.push(...compareRoutes(ios?.routes, android?.routes));
+    return { ios: ios?.routes, android: android?.routes };
+}
+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 androidApps = discovered.flatMap(([, android]) => android);
@@ -60,10 +71,12 @@ export async function run({ roots, source, sha256, onDiscovered }) {
         });
     }
     findings.push(...checkCrossPlatform(ios, android));
+    const routeTables = routes ? await runRouteChecks(routes, roots, findings) : undefined;
     return {
         iosApps,
         androidApps,
         domains: [...new Set([...ios.domains, ...android.domains])],
+        routes: routeTables,
         findings,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deeplink-parity",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Checks that what your mobile app declares about deep links matches what is actually hosted — across iOS and Android.",
   "type": "module",
   "bin": {
@@ -37,9 +37,11 @@
   },
   "dependencies": {
     "fast-xml-parser": "^5.10.1",
+    "js-yaml": "^5.2.3",
     "plist": "^3.1.0"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.10.0",
     "@types/plist": "^3.0.5",
     "tsx": "^4.19.0",