@mcamdali/sdkbump 0.0.0-stage → 0.1.3

package/dist/cli/run.d.ts

@@ -0,0 +1,29 @@
+import type { Report } from '../model.js';
+/** Exit codes; documented in the README and `--help`. */
+export declare const EXIT: {
+    readonly ok: 0;
+    readonly findings: 1;
+    readonly error: 2;
+};
+export declare const FAIL_ON: readonly ['error', 'warning', 'info', 'none'];
+type FailOn = (typeof FAIL_ON)[number];
+/** Everything the CLI touches outside its arguments, so tests can run it in-process. */
+export interface CliEnvironment {
+    cwd: string;
+    env: Record<string, string | undefined>;
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    /** Whether stdout is a terminal; turns colour on for the tty format. */
+    stdoutIsTty: boolean;
+    /** Terminal width, when stdout is a terminal. */
+    columns?: number | undefined;
+}
+/** The npm package; the command it installs is `sdkbump`. */
+export declare const PACKAGE_NAME = "@mcamdali/sdkbump";
+/** The tarball the GitHub release of this version carries (the same file as on npm). */
+export declare const RELEASE_TARBALL_URL: string;
+/** Whether the report has an unhandled finding at or above `failOn`. */
+export declare function failsOn(report: Report, failOn: FailOn): boolean;
+/** Runs the CLI with the given arguments (without `node` and the script) and returns the exit code. */
+export declare function run(argv: readonly string[], environment: CliEnvironment): Promise<number>;
+export {};

package/dist/cli/run.js

@@ -0,0 +1,111 @@
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { Command, CommanderError, Option } from 'commander';
+import { ProjectError } from '../detect/project.js';
+import { FORMATS, render } from '../report/index.js';
+import { clean, REPOSITORY_URL } from '../report/text.js';
+import { scan } from '../scan.js';
+import { VERSION } from '../version.js';
+/** Exit codes; documented in the README and `--help`. */
+export const EXIT = { ok: 0, findings: 1, error: 2 };
+export const FAIL_ON = ['error', 'warning', 'info', 'none'];
+/** The npm package; the command it installs is `sdkbump`. */
+export const PACKAGE_NAME = '@mcamdali/sdkbump';
+/** The tarball the GitHub release of this version carries (the same file as on npm). */
+export const RELEASE_TARBALL_URL = `${REPOSITORY_URL}/releases/download/v${VERSION}/sdkbump-${VERSION}.tgz`;
+const HELP_AFTER = `
+Exit codes:
+  0  no findings at or above --fail-on (findings a workaround handles do not count)
+  1  findings at or above --fail-on
+  2  bad arguments, no iOS project found, or an unexpected error
+
+Examples:
+  sdkbump                              checks the project in the current folder
+  sdkbump path/to/app --format markdown --output sdkbump.md
+  sdkbump --format json > sdkbump.json
+  sdkbump --fail-on warning            also fails on warnings, e.g. in CI
+
+The npm package is ${PACKAGE_NAME}; the command is sdkbump:
+  npx ${PACKAGE_NAME}                runs the latest version without installing it
+  npm i -g ${PACKAGE_NAME}           installs the sdkbump command
+  npx ${RELEASE_TARBALL_URL}
+                                       runs this release from GitHub
+
+Docs: ${REPOSITORY_URL}#readme`;
+function program(io) {
+    return new Command('sdkbump')
+        .description('Checks a native iOS, Flutter or React Native/Expo project for what the iOS 27 SDK changes, starting with the UIScene life cycle, and says which fix applies to each finding.')
+        .version(VERSION, '-v, --version')
+        .argument('[path]', 'project folder or .xcodeproj (default: current folder)')
+        .addOption(new Option('-f, --format <format>', 'output format').choices(FORMATS).default('tty'))
+        .option('-o, --output <file>', 'write the report to a file instead of stdout')
+        .addOption(new Option('--fail-on <severity>', 'lowest severity that makes the exit code 1')
+        .choices(FAIL_ON)
+        .default('error'))
+        .option('--no-color', 'plain text even in a terminal')
+        .addHelpText('after', HELP_AFTER)
+        .showHelpAfterError('(add --help for usage)')
+        .exitOverride()
+        .configureOutput({
+        writeOut: io.stdout,
+        writeErr: io.stderr,
+        outputError: (text, write) => write(text),
+    });
+}
+function useColor(options, io) {
+    if (options.format !== 'tty' || options.output || !options.color)
+        return false;
+    if (io.env.NO_COLOR)
+        return false;
+    if (io.env.FORCE_COLOR && io.env.FORCE_COLOR !== '0')
+        return true;
+    return io.stdoutIsTty;
+}
+const RANK = { error: 3, warning: 2, info: 1 };
+/** Whether the report has an unhandled finding at or above `failOn`. */
+export function failsOn(report, failOn) {
+    if (failOn === 'none')
+        return false;
+    return report.findings.some((item) => !item.mitigation && RANK[item.severity] >= RANK[failOn]);
+}
+/** Runs the CLI with the given arguments (without `node` and the script) and returns the exit code. */
+export async function run(argv, environment) {
+    // Messages name folders, files and targets of the checked project, and the verdict after
+    // --output names a target. Every write to stderr is cleaned here, so none of them can carry an
+    // escape sequence to the terminal.
+    const io = { ...environment, stderr: (text) => environment.stderr(clean(text)) };
+    const command = program(io);
+    try {
+        await command.parseAsync([...argv], { from: 'user' });
+    }
+    catch (error) {
+        if (error instanceof CommanderError)
+            return error.exitCode === 0 ? EXIT.ok : EXIT.error;
+        throw error;
+    }
+    const options = command.opts();
+    const path = command.processedArgs[0] ?? '.';
+    try {
+        const report = await scan(resolve(io.cwd, path));
+        report.project.path = path;
+        const width = io.stdoutIsTty && io.columns ? Math.min(io.columns, 100) : 100;
+        const output = render(report, options.format, { color: useColor(options, io), width });
+        if (options.output) {
+            await writeFile(resolve(io.cwd, options.output), output);
+            io.stderr(`Wrote ${options.output}: ${report.verdict.text}\n`);
+        }
+        else {
+            io.stdout(output);
+        }
+        return failsOn(report, options.failOn) ? EXIT.findings : EXIT.ok;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        io.stderr(`sdkbump: ${message}\n`);
+        if (!(error instanceof ProjectError)) {
+            io.stderr(`This looks like a bug in sdkbump; please report it at ${REPOSITORY_URL}/issues\n`);
+        }
+        return EXIT.error;
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/collect/app.d.ts

@@ -0,0 +1,48 @@
+import type { Project } from '../detect/project.js';
+import type { InfoPlistSource } from '../model.js';
+import { type PlistDict } from './plist.js';
+import { type SourceIndex } from './sources.js';
+export interface InfoPlistFile {
+    path: string;
+    dict: PlistDict;
+    keyLines: ReadonlyMap<string, number>;
+}
+export interface AppTarget {
+    name: string;
+    /** The .xcodeproj the target belongs to. */
+    xcodeProject: string;
+    infoPlists: InfoPlistFile[];
+    /** Xcode generates (part of) the Info.plist: GENERATE_INFOPLIST_FILE = YES. */
+    generatesInfoPlist: boolean;
+    /**
+     * Where the rules get the Info.plist from: a file sdkbump read, the one Xcode generates from
+     * build settings, or none (not-read) when the file could not be read or the project file does
+     * not say which one it is.
+     */
+    infoPlistSource: InfoPlistSource;
+}
+export interface AppModel {
+    project: Project;
+    targets: AppTarget[];
+    sources: SourceIndex;
+    /** Problems reading the project that the report should mention. */
+    notes: string[];
+}
+/** Reads the app targets and sources of a detected project. */
+export declare function collectApp(project: Project): Promise<AppModel>;
+/** The scene manifest of an Info.plist and whether it lists at least one configuration. */
+export declare function sceneManifest(plist: InfoPlistFile): {
+    present: boolean;
+    configured: boolean;
+};
+/** Path of the Flutter Runner's AppDelegate files, for the auto-migration check. */
+export declare const flutterAppDelegatePaths: (iosDir: string) => {
+    swift: string;
+    objcHeader: string;
+    objcImplementation: string;
+};
+/**
+ * The scene delegate classes an Info.plist names in its scene configurations, without a module
+ * prefix: "$(PRODUCT_MODULE_NAME).SceneDelegate" and "App.SceneDelegate" both give "SceneDelegate".
+ */
+export declare function sceneDelegateClassNames(plist: InfoPlistFile): string[];

package/dist/collect/app.js

@@ -0,0 +1,117 @@
+// Everything the rules look at for one project: its iOS app targets with their Info.plist, and
+// the index of the app's own Swift and Objective-C sources.
+import { join } from 'node:path';
+import { NOT_READ, readProjectFile } from '../core/files.js';
+import { generatesInfoPlist, infoPlistFiles, iosAppTargets, readXcodeProject, } from './pbxproj.js';
+import { isDict, parsePlist } from './plist.js';
+import { indexSources } from './sources.js';
+/**
+ * Reads the Info.plist a target names. INFOPLIST_FILE comes from the checked project, so a path
+ * that leads (through `..`, an absolute path or a symbolic link) outside the project folder is
+ * not read, and neither is anything but a regular file: /dev/zero would never end.
+ */
+async function readInfoPlist(path, projectRoot, notes) {
+    const file = await readProjectFile(path, projectRoot);
+    if (!file.found) {
+        notes.push(`${path} is named in INFOPLIST_FILE but ${NOT_READ[file.reason]}`);
+        return null;
+    }
+    try {
+        const { value, keyLines } = parsePlist(file.bytes);
+        if (!isDict(value))
+            throw new Error('the top level is not a dictionary');
+        return { path, dict: value, keyLines };
+    }
+    catch (error) {
+        notes.push(`${path} could not be read as a property list: ${error.message}`);
+        return null;
+    }
+}
+/**
+ * Reads one app target's Info.plist. A target that names no INFOPLIST_FILE and does not have
+ * Xcode generate one most likely sets it in an .xcconfig file, which sdkbump does not read.
+ */
+async function readTarget(xcode, target, projectRoot, notes) {
+    const { files, unresolved } = infoPlistFiles(xcode, target);
+    for (const raw of unresolved) {
+        notes.push(`${target.name}: INFOPLIST_FILE ${raw} uses a build setting sdkbump does not expand.`);
+    }
+    const infoPlists = [];
+    for (const file of files) {
+        const plist = await readInfoPlist(file, projectRoot, notes);
+        if (plist)
+            infoPlists.push(plist);
+    }
+    const generates = generatesInfoPlist(target);
+    const named = files.length + unresolved.length > 0;
+    if (!named && !generates) {
+        notes.push(`${target.name}: the Xcode project sets neither INFOPLIST_FILE nor GENERATE_INFOPLIST_FILE = YES; they may be set in an .xcconfig file, which sdkbump does not read.`);
+    }
+    let infoPlistSource = 'not-read';
+    if (infoPlists.length > 0)
+        infoPlistSource = 'file';
+    else if (!named && generates)
+        infoPlistSource = 'generated';
+    return {
+        name: target.name,
+        xcodeProject: xcode.path,
+        infoPlists,
+        generatesInfoPlist: generates,
+        infoPlistSource,
+    };
+}
+/** Reads the app targets and sources of a detected project. */
+export async function collectApp(project) {
+    const notes = [];
+    const targets = [];
+    for (const path of project.xcodeProjects) {
+        let xcode;
+        try {
+            xcode = await readXcodeProject(path, project.root);
+        }
+        catch (error) {
+            notes.push(`${path}: ${error.message}`);
+            continue;
+        }
+        for (const target of iosAppTargets(xcode)) {
+            targets.push(await readTarget(xcode, target, project.root, notes));
+        }
+    }
+    if (project.iosDir && project.xcodeProjects.length > 0 && targets.length === 0) {
+        notes.push('No iOS app target was found in the Xcode project.');
+    }
+    const sources = await indexSources(project.iosDir ? [project.iosDir] : []);
+    return { project, targets, sources, notes };
+}
+/** The scene manifest of an Info.plist and whether it lists at least one configuration. */
+export function sceneManifest(plist) {
+    const manifest = plist.dict.UIApplicationSceneManifest;
+    if (!isDict(manifest))
+        return { present: false, configured: false };
+    const configurations = manifest.UISceneConfigurations;
+    const configured = isDict(configurations) &&
+        Object.values(configurations).some((roles) => Array.isArray(roles) && roles.length > 0);
+    return { present: true, configured };
+}
+/** Path of the Flutter Runner's AppDelegate files, for the auto-migration check. */
+export const flutterAppDelegatePaths = (iosDir) => ({
+    swift: join(iosDir, 'Runner', 'AppDelegate.swift'),
+    objcHeader: join(iosDir, 'Runner', 'AppDelegate.h'),
+    objcImplementation: join(iosDir, 'Runner', 'AppDelegate.m'),
+});
+/**
+ * The scene delegate classes an Info.plist names in its scene configurations, without a module
+ * prefix: "$(PRODUCT_MODULE_NAME).SceneDelegate" and "App.SceneDelegate" both give "SceneDelegate".
+ */
+export function sceneDelegateClassNames(plist) {
+    const configurations = plist.dict.UIApplicationSceneManifest
+        ?.UISceneConfigurations;
+    if (!isDict(configurations))
+        return [];
+    return Object.values(configurations)
+        .flatMap((roles) => (Array.isArray(roles) ? roles : []))
+        .map((entry) => (isDict(entry) ? entry.UISceneDelegateClassName : undefined))
+        .filter((name) => typeof name === 'string')
+        .map((name) => name.split('.').at(-1) ?? name);
+}
+//# sourceMappingURL=app.js.map

package/dist/collect/blank.d.ts

@@ -0,0 +1,6 @@
+import type { Language } from './sources.js';
+/**
+ * Replaces comments and the contents of string and character literals with spaces, keeping
+ * newlines and quote characters, so offsets and line numbers stay the same.
+ */
+export declare function blankCommentsAndStrings(text: string, language: Language): string;

package/dist/collect/blank.js

@@ -0,0 +1,75 @@
+/**
+ * Replaces comments and the contents of string and character literals with spaces, keeping
+ * newlines and quote characters, so offsets and line numbers stay the same.
+ */
+export function blankCommentsAndStrings(text, language) {
+    const out = text.split('');
+    const blank = (from, to) => {
+        for (let index = from; index < to; index++)
+            if (out[index] !== '\n')
+                out[index] = ' ';
+    };
+    let index = 0;
+    while (index < text.length) {
+        const char = text[index];
+        const next = text[index + 1];
+        if (char === '/' && next === '/') {
+            const end = text.indexOf('\n', index);
+            const stop = end === -1 ? text.length : end;
+            blank(index, stop);
+            index = stop;
+        }
+        else if (char === '/' && next === '*') {
+            // Swift block comments nest; Objective-C ones do not.
+            let depth = 1;
+            let cursor = index + 2;
+            while (cursor < text.length && depth > 0) {
+                if (text.startsWith('*/', cursor)) {
+                    depth--;
+                    cursor += 2;
+                }
+                else if (language === 'swift' && text.startsWith('/*', cursor)) {
+                    depth++;
+                    cursor += 2;
+                }
+                else
+                    cursor++;
+            }
+            blank(index, cursor);
+            index = cursor;
+        }
+        else if (language === 'swift' &&
+            (char === '"' || (char === '#' && /^#+"/.test(text.slice(index, index + 8))))) {
+            const hashes = /^#*/.exec(text.slice(index))?.[0].length ?? 0;
+            const open = index + hashes;
+            const multiline = text.startsWith('"""', open);
+            const closing = `${multiline ? '"""' : '"'}${'#'.repeat(hashes)}`;
+            let cursor = open + (multiline ? 3 : 1);
+            while (cursor < text.length) {
+                if (hashes === 0 && text[cursor] === '\\')
+                    cursor += 2;
+                else if (text.startsWith(closing, cursor))
+                    break;
+                else if (!multiline && text[cursor] === '\n')
+                    break;
+                else
+                    cursor++;
+            }
+            const contentEnd = Math.min(cursor, text.length);
+            blank(open + (multiline ? 3 : 1), contentEnd);
+            index = contentEnd + (text.startsWith(closing, contentEnd) ? closing.length : 0);
+        }
+        else if (language === 'objc' && (char === '"' || char === "'")) {
+            let cursor = index + 1;
+            while (cursor < text.length && text[cursor] !== char && text[cursor] !== '\n') {
+                cursor += text[cursor] === '\\' ? 2 : 1;
+            }
+            blank(index + 1, Math.min(cursor, text.length));
+            index = cursor + 1;
+        }
+        else
+            index++;
+    }
+    return out.join('');
+}
+//# sourceMappingURL=blank.js.map

package/dist/collect/pbxproj.d.ts

@@ -0,0 +1,45 @@
+export type OpenStepValue = string | OpenStepValue[] | OpenStepDict;
+export interface OpenStepDict {
+    [key: string]: OpenStepValue;
+}
+export declare class XcodeProjectError extends Error {
+    name: string;
+}
+/** Parses an old-style property list such as project.pbxproj. */
+export declare function parseOpenStep(text: string): OpenStepValue;
+export type BuildSettings = Readonly<Record<string, string | readonly string[]>>;
+export interface XcodeTarget {
+    name: string;
+    productType: string;
+    /** Build settings per configuration (Debug, Release, …), project-level values included. */
+    configurations: Readonly<Record<string, BuildSettings>>;
+}
+export interface XcodeProject {
+    /** Path of the .xcodeproj folder. */
+    path: string;
+    /** The folder that contains the .xcodeproj, which $(SRCROOT) refers to. */
+    sourceRoot: string;
+    targets: XcodeTarget[];
+}
+/** Reads the native targets of a parsed project.pbxproj. */
+export declare function readTargets(pbxproj: OpenStepValue): XcodeTarget[];
+/**
+ * Reads `<path>.xcodeproj/project.pbxproj` when it is a regular file inside `root` (by default
+ * the .xcodeproj folder itself).
+ */
+export declare function readXcodeProject(path: string, root?: string): Promise<XcodeProject>;
+/** Whether the target builds with the iOS SDK (SDKROOT iphoneos, or `auto` listing iphoneos). */
+export declare function buildsForIOS(settings: BuildSettings): boolean;
+/** iOS app targets (apps and App Clips): the ones UIKit's launch check applies to. */
+export declare function iosAppTargets(project: XcodeProject): XcodeTarget[];
+/**
+ * The Info.plist files a target's configurations name in INFOPLIST_FILE, as absolute paths.
+ * $(SRCROOT), $(PROJECT_DIR), $(TARGET_NAME) and $(PRODUCT_NAME) are expanded; a path that still
+ * contains an unknown variable is returned in `unresolved`.
+ */
+export declare function infoPlistFiles(project: XcodeProject, target: XcodeTarget): {
+    files: string[];
+    unresolved: string[];
+};
+/** Whether every configuration of the target has Xcode generate (part of) its Info.plist. */
+export declare function generatesInfoPlist(target: XcodeTarget): boolean;