deeplink-parity 0.6.4 → 0.7.0

package/README.md

@@ -59,8 +59,8 @@ npx deeplink-parity ./my-app-ios ./my-app-android
 ```
 
 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.
+key in the check. Already have findings? Freeze them once with `npx deeplink-parity
+baseline` and commit the file — the check then fails only on new ones.
 
 Domains are checked with zero setup. To also compare the **screens behind the links**,
 run `npx deeplink-parity init` once — see [Route parity](#route-parity).
@@ -74,6 +74,7 @@ run `npx deeplink-parity init` once — see [Route parity](#route-parity).
 - [Usage](#usage)
   - [GitHub Action](#github-action)
   - [In CI](#in-ci)
+  - [Start with existing findings](#start-with-existing-findings)
   - [Run it on a schedule](#run-it-on-a-schedule)
   - [Validate before deploying](#validate-before-deploying)
 - [Route parity](#route-parity)
@@ -135,10 +136,12 @@ No configuration file. Domains are discovered from your app, then the matching w
 ```bash
 npx deeplink-parity [path...] [options]        # check (default)
 npx deeplink-parity init [path...]             # interactive setup for route comparison
+npx deeplink-parity baseline [path...]         # freeze current findings; fail on new ones only
 
   --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)
+  --baseline <file>        Baseline file (default: deeplink-parity-baseline.json 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
@@ -186,6 +189,7 @@ Findings appear as annotations on the run, and counts are available to later ste
 | `sha256` | — | Android signing fingerprint |
 | `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 |
 | `version` | pinned | npm version to run |
 
@@ -204,6 +208,24 @@ 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.
 
+### Start with existing findings
+
+A tool that fails on day one gets turned off on day two. If the first run reports
+problems you cannot fix immediately, freeze them:
+
+```bash
+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
+can read what is being tolerated. When a baselined problem gets fixed, the check says
+so; re-run `baseline` to tighten the file.
+
+A known problem keeps its identity when the failure changes shape — a domain that
+answered 404 yesterday and times out today is still one known problem, not a new alert.
+
 ### 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:

package/dist/baseline.js

@@ -0,0 +1,69 @@
+import { access, readFile, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+export const BASELINE_NAME = 'deeplink-parity-baseline.json';
+/**
+ * Identity of a finding across runs. Domain problems key on rule + domain so a failure
+ * that changes shape (404 today, timeout tomorrow) stays one known problem; findings
+ * without a domain (route gaps) carry their identity in the message.
+ */
+export function baselineKey(f) {
+    return `${f.rule}|${f.domain ?? f.message}`;
+}
+/** Same lookup order as the route config: an explicit path wins, then cwd, then roots. */
+export async function findBaseline(explicit, roots) {
+    if (explicit)
+        return resolve(explicit);
+    for (const dir of [process.cwd(), ...roots]) {
+        const candidate = join(dir, BASELINE_NAME);
+        try {
+            await access(candidate);
+            return candidate;
+        }
+        catch {
+            // keep looking
+        }
+    }
+    return undefined;
+}
+export async function loadBaseline(path) {
+    const raw = JSON.parse(await readFile(path, 'utf8'));
+    if (!Array.isArray(raw?.entries)) {
+        throw new Error(`${path} is not a baseline file — expected an "entries" array`);
+    }
+    return new Set(raw.entries.map((e) => e.key));
+}
+/** Only findings that can fail a run belong in a baseline; info never fails. */
+export async function writeBaseline(path, findings) {
+    const entries = new Map();
+    for (const f of findings) {
+        if (f.severity === 'info')
+            continue;
+        const key = baselineKey(f);
+        if (!entries.has(key)) {
+            entries.set(key, { key, summary: [f.domain, f.message].filter(Boolean).join(' — ') });
+        }
+    }
+    const sorted = [...entries.values()].sort((a, b) => a.key.localeCompare(b.key));
+    await writeFile(path, `${JSON.stringify({ entries: sorted }, null, 2)}\n`);
+    return sorted.length;
+}
+/**
+ * Marks known findings in place and reports which baseline entries are now stale.
+ * Exit-code policy lives in exitCodeFor: a baselined error no longer fails the run.
+ */
+export function applyBaseline(findings, baseline) {
+    const seen = new Set();
+    for (const f of findings) {
+        if (f.severity === 'info')
+            continue;
+        const key = baselineKey(f);
+        if (baseline.has(key)) {
+            f.baselined = true;
+            seen.add(key);
+        }
+    }
+    return {
+        matched: seen.size,
+        resolved: [...baseline].filter((k) => !seen.has(k)).sort(),
+    };
+}

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFile, stat, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { applyBaseline, BASELINE_NAME, findBaseline, loadBaseline, writeBaseline } from './baseline.js';
 import { localSource, networkSource } from './fetch/wellKnown.js';
 import { exitCodeFor, printReport } from './report/console.js';
 import { printGithubAnnotations } from './report/github.js';
@@ -13,6 +14,7 @@ matches what is actually hosted, across iOS and Android.
 Usage
   deeplink-parity [path...] [options]        check (default)
   deeplink-parity init [path...]             interactive setup for route comparison
+  deeplink-parity baseline [path...]         freeze current findings; checks then fail on new ones only
 
   Pass one path per checkout. iOS and Android usually live in separate
   repositories, and comparing them is the point:
@@ -23,6 +25,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
   --config <file>          Route config (default: deeplink-parity.yml in cwd or a root)
+  --baseline <file>        Baseline file (default: deeplink-parity-baseline.json 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
@@ -47,6 +50,7 @@ function parseArgs(argv) {
     let wellKnown;
     let output;
     let config;
+    let baseline;
     // 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++) {
@@ -71,11 +75,13 @@ function parseArgs(argv) {
             output = args[++i];
         else if (arg === '--config')
             config = args[++i];
+        else if (arg === '--baseline')
+            baseline = args[++i];
         else if (!arg.startsWith('-'))
             positional.push(arg);
     }
-    const command = positional[0] === 'init' ? 'init' : 'check';
-    const roots = (command === 'init' ? positional.slice(1) : positional).map((r) => resolve(r));
+    const command = positional[0] === 'init' || positional[0] === 'baseline' ? positional[0] : 'check';
+    const roots = (command === 'check' ? positional : positional.slice(1)).map((r) => resolve(r));
     return {
         command,
         roots: roots.length ? roots : [resolve('.')],
@@ -88,6 +94,7 @@ function parseArgs(argv) {
         wellKnown,
         output,
         config,
+        baseline,
         format,
     };
 }
@@ -130,6 +137,9 @@ async function main() {
     }
     const configPath = await findConfig(opts.config, opts.roots);
     const routes = configPath ? await loadRoutesConfig(configPath) : undefined;
+    // the baseline subcommand regenerates the file, so it must not also consume one
+    const baselinePath = opts.command === 'baseline' ? undefined : await findBaseline(opts.baseline, opts.roots);
+    const baseline = baselinePath ? await loadBaseline(baselinePath) : undefined;
     const source = opts.wellKnown ? localSource(resolve(opts.wellKnown)) : networkSource();
     const result = await run({
         roots: opts.roots,
@@ -143,6 +153,26 @@ async function main() {
             }
         },
     });
+    if (opts.command === 'baseline') {
+        const target = opts.baseline ? resolve(opts.baseline) : resolve(BASELINE_NAME);
+        const count = await writeBaseline(target, result.findings);
+        console.log(`Froze ${count} finding(s) into ${target}`);
+        console.log('Commit it. From now on the check fails only on findings that are not in this file.');
+        console.log('Re-run `deeplink-parity baseline` after fixing something, to tighten it.');
+        return;
+    }
+    const applied = baseline ? applyBaseline(result.findings, baseline) : undefined;
+    if (applied) {
+        for (const key of applied.resolved) {
+            result.findings.push({
+                severity: 'info',
+                rule: 'baseline-resolved',
+                message: `A baselined finding no longer occurs: ${key}`,
+                detail: 'Re-run `deeplink-parity baseline` to tighten the baseline.',
+                source: baselinePath,
+            });
+        }
+    }
     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(', ')}`);
@@ -162,6 +192,7 @@ async function main() {
     const payload = {
         version: pkg.version,
         routeConfig: configPath,
+        baseline: baselinePath ? { path: baselinePath, matched: applied?.matched ?? 0 } : undefined,
         ios: result.iosApps.map((a) => ({
             entitlements: a.entitlementsPath,
             teamId: a.teamId,
@@ -193,12 +224,16 @@ async function main() {
     // machine-readable output in the same run.
     if (opts.output)
         await writeFile(opts.output, `${JSON.stringify(payload, null, 2)}\n`);
-    const routesLine = configPath
+    const baselineLine = baselinePath
+        ? ` · baseline: ${applied?.matched ?? 0} known finding(s), failing on new only`
+        : '';
+    const routesLine = (configPath
         ? `routes: ${configPath}` +
             (result.routes
                 ? ` (iOS ${result.routes.ios?.paths.length ?? 0} · Android ${result.routes.android?.paths.length ?? 0})`
                 : '')
-        : 'routes: no config found — run "deeplink-parity init" to compare route tables';
+        : 'routes: no config found — run "deeplink-parity init" to compare route tables') +
+        baselineLine;
     if (opts.json) {
         console.log(JSON.stringify(payload, null, 2));
     }

package/dist/report/console.js

@@ -28,7 +28,8 @@ export function printReport(findings, checkedDomains, meta) {
             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);
-            console.log(`${head}  ${subject}`);
+            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)}`);
@@ -41,6 +42,7 @@ export function printReport(findings, checkedDomains, meta) {
     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') ? 1 : 0;
+    return findings.some((f) => f.severity === 'error' && !f.baselined) ? 1 : 0;
 }

package/dist/report/github.js

@@ -18,6 +18,8 @@ function escapeProperty(value) {
  */
 export function printGithubAnnotations(findings) {
     for (const f of findings) {
+        // 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}`)}`];
         // 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
@@ -25,7 +27,9 @@ export function printGithubAnnotations(findings) {
         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)}`);
+        const body = [f.baselined ? '(baselined)' : '', f.domain, f.message, f.detail]
+            .filter(Boolean)
+            .join(' — ');
+        console.log(`::${level} ${props.join(',')}::${escapeData(body)}`);
     }
 }

package/dist/routes/init.js

@@ -83,6 +83,12 @@ async function pickRegex(rl, files, yes) {
  * after printing its full content and asking. The scanned repositories are never touched.
  */
 export async function runInit(roots, yes) {
+    // Without a terminal the prompts get EOF and the process would exit 0 having done
+    // nothing — a silent success, which is worse than a hang.
+    if (!yes && !process.stdin.isTTY) {
+        console.error('init is interactive — run it in a terminal, or pass --yes to accept the top suggestions.');
+        return 2;
+    }
     console.log(`Scanning ${roots.length} root(s) for route tables…`);
     const candidates = await findCandidates(roots);
     const rl = createInterface({ input: process.stdin, output: process.stdout });

package/package.json

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