@dualkit/convert 0.0.0-stage → 0.2.0-beta.0

package/dist/index.d.cts

@@ -0,0 +1,173 @@
+/** One text replacement, as offsets into `SourceFile.text`. */
+type Edit = {
+    start: number;
+    end: number;
+    text: string;
+};
+type FlagKind = 'no-logical-form' | 'computed-class' | 'inline-svg-icon' | 'mixed-text' | 'outside-component' | 'format' | 'unparsed' | 'unsupported' | 'info';
+/** Something convert left for a person or agent to finish. */
+type Flag = {
+    file: string;
+    line: number;
+    kind: FlagKind;
+    message: string;
+    suggestion: string;
+};
+/** What a transform pass returns for one file. */
+type FileResult = {
+    edits: Edit[];
+    flags: Flag[];
+};
+/** `bilingual` keeps English and adds Arabic; `arabic` converts in place. */
+type Mode = 'bilingual' | 'arabic';
+/** Optional settings read from the app's dualkit config. */
+type ConvertConfig = {
+    start?: string;
+    port?: number;
+    routes?: string[];
+    params?: Record<string, string>;
+    storageState?: string;
+    test?: string;
+};
+/** What convert detected about the app it will convert. `entry` is the root layout (Next) or the createRoot file (Vite). */
+type Project = {
+    root: string;
+    framework: 'next-app' | 'vite-react';
+    appDir: string | null;
+    entry: string;
+    tailwind: string | null;
+    i18n: 'next-intl' | 'react-i18next' | null;
+    packageManager: 'npm' | 'pnpm' | 'yarn' | 'bun';
+};
+/** Answers the person gave at a prompt. They are merged into dualkit.config.json under `convert` and committed. */
+type ConfigAnswers = {
+    start?: string;
+    port?: number;
+};
+/** What phase 1 is asked to do. `root` is the app folder, inside a git repo. `configFile` is relative to root, dualkit.config.json by default. */
+type ConvertOptions = {
+    root: string;
+    mode: Mode;
+    install: boolean;
+    baseline: boolean;
+    configAnswers?: ConfigAnswers;
+    configFile?: string;
+};
+/** What phase 2 is asked to do. `force` uses English for pending strings. `configFile` is as for ConvertOptions. */
+type FinishOptions = {
+    root: string;
+    force?: boolean;
+    configAnswers?: ConfigAnswers;
+    configFile?: string;
+};
+/** Per-request browser settings. `cookies` are set before the page loads. */
+type PageOptions = {
+    cookies?: Record<string, string>;
+};
+/** Takes a screenshot of url at a viewport width and returns the PNG. Injected by the CLI. */
+type Shooter = (url: string, width: number, options?: PageOptions) => Promise<Buffer>;
+/** What convert needs from outside: a logger, a command runner, the app's config, for the baseline a shooter, and an interrupt signal. */
+type ConvertIo = {
+    log: (s: string) => void;
+    shoot?: Shooter;
+    run: (cmd: string, cwd: string) => Promise<{
+        code: number;
+        out: string;
+    }>;
+    config: ConvertConfig;
+    /** Fires when the person interrupts the run. Convert checks it after slow steps and rolls back. */
+    signal?: AbortSignal;
+};
+/** The passes that make edits, plus wiring. */
+type EditKind = 'tailwind' | 'css' | 'markup' | 'strings' | 'formats' | 'wiring';
+/** What a phase 1 run changed and left to finish. */
+type ConvertSummary = {
+    branch: string;
+    filesChanged: number;
+    edits: number;
+    /** Applied edits per pass. Wiring counts its edits plus the files it wrote. */
+    byKind: Record<EditKind, number>;
+    /** Files with applied edits, at post-move paths, sorted by file. */
+    changed: {
+        file: string;
+        edits: number;
+    }[];
+    flags: Flag[];
+    strings: number;
+    skipped: {
+        file: string;
+        reason: string;
+    }[];
+};
+/** Saved to `.dualkit/convert.json`. `generated` lists the files convert wrote, which later runs leave alone. */
+type ConvertState = {
+    mode: Mode;
+    base: string;
+    branch: string;
+    framework: Project['framework'];
+    phase: 'converted' | 'finished';
+    generated: string[];
+};
+
+/** Thrown when two edits touch the same span. */
+declare class OverlapError extends Error {
+    readonly first: Edit;
+    readonly second: Edit;
+    constructor(first: Edit, second: Edit);
+}
+/**
+ * Applies non-overlapping edits in any order. Edits that start at the same offset apply in their given
+ * order, so an insert listed before a replacement at that offset lands before it. Throws on an edit
+ * outside the text.
+ */
+declare function applyEdits(text: string, edits: Edit[]): string;
+
+/** Thrown when the app is not one convert can handle. The message names what is supported. */
+declare class UnsupportedError extends Error {
+    constructor(message: string);
+}
+/** Reads the app at root and says which framework, entry, styling and tooling it uses. Throws UnsupportedError for anything else. */
+declare function detectProject(root: string): Project;
+
+/** The branch a mode converts on. */
+declare const branchFor: (mode: Mode) => string;
+/** The flags a person or agent still has to act on. Info flags are kept in the summary but are never problems. */
+declare const problems: (flags: readonly Flag[]) => Flag[];
+/**
+ * Phase 1: converts the app at `options.root` on the branch `dualkit/<mode>` and commits it with the
+ * person's own git identity. Transforms run in memory first, so a refusal changes nothing. A re-run on
+ * a branch convert already converted runs again in place and commits only when something changed.
+ */
+declare function convert(options: ConvertOptions, ioIn: ConvertIo): Promise<ConvertSummary>;
+
+/** Thrown when convert will not start. The message is one line saying why. */
+declare class RefusedError extends Error {
+    constructor(message: string);
+}
+
+/** Thrown when a run fails after the branch was created. The message names the step and where the repo now is. */
+declare class ConvertFailedError extends Error {
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+
+/** What phase 2 needs from outside: phase 1's io plus an accessibility audit and a lint count. */
+type FinishIo = ConvertIo & {
+    audit: (url: string, width: number, options?: PageOptions) => Promise<{
+        score: number;
+        errors: number;
+        warnings: number;
+    }>;
+    lint: (root: string) => Promise<number>;
+};
+/**
+ * Phase 2: writes the messages from the ledger, serves the app, checks English against the baseline and
+ * audits the Arabic pages, writes dualkit-convert.md and commits it with the messages and the ledger.
+ * When a step fails after writing starts, finish puts its own files back and commits nothing.
+ */
+declare function finish(options: FinishOptions, ioIn: FinishIo): Promise<{
+    reportPath: string;
+    passed: boolean;
+}>;
+
+export { type ConfigAnswers, type ConvertConfig, ConvertFailedError, type ConvertIo, type ConvertOptions, type ConvertState, type ConvertSummary, type Edit, type FileResult, type FinishIo, type FinishOptions, type Flag, type FlagKind, type Mode, OverlapError, type Project, RefusedError, type Shooter, UnsupportedError, applyEdits, branchFor, convert, detectProject, finish, problems };

package/dist/index.d.ts

@@ -0,0 +1,173 @@
+/** One text replacement, as offsets into `SourceFile.text`. */
+type Edit = {
+    start: number;
+    end: number;
+    text: string;
+};
+type FlagKind = 'no-logical-form' | 'computed-class' | 'inline-svg-icon' | 'mixed-text' | 'outside-component' | 'format' | 'unparsed' | 'unsupported' | 'info';
+/** Something convert left for a person or agent to finish. */
+type Flag = {
+    file: string;
+    line: number;
+    kind: FlagKind;
+    message: string;
+    suggestion: string;
+};
+/** What a transform pass returns for one file. */
+type FileResult = {
+    edits: Edit[];
+    flags: Flag[];
+};
+/** `bilingual` keeps English and adds Arabic; `arabic` converts in place. */
+type Mode = 'bilingual' | 'arabic';
+/** Optional settings read from the app's dualkit config. */
+type ConvertConfig = {
+    start?: string;
+    port?: number;
+    routes?: string[];
+    params?: Record<string, string>;
+    storageState?: string;
+    test?: string;
+};
+/** What convert detected about the app it will convert. `entry` is the root layout (Next) or the createRoot file (Vite). */
+type Project = {
+    root: string;
+    framework: 'next-app' | 'vite-react';
+    appDir: string | null;
+    entry: string;
+    tailwind: string | null;
+    i18n: 'next-intl' | 'react-i18next' | null;
+    packageManager: 'npm' | 'pnpm' | 'yarn' | 'bun';
+};
+/** Answers the person gave at a prompt. They are merged into dualkit.config.json under `convert` and committed. */
+type ConfigAnswers = {
+    start?: string;
+    port?: number;
+};
+/** What phase 1 is asked to do. `root` is the app folder, inside a git repo. `configFile` is relative to root, dualkit.config.json by default. */
+type ConvertOptions = {
+    root: string;
+    mode: Mode;
+    install: boolean;
+    baseline: boolean;
+    configAnswers?: ConfigAnswers;
+    configFile?: string;
+};
+/** What phase 2 is asked to do. `force` uses English for pending strings. `configFile` is as for ConvertOptions. */
+type FinishOptions = {
+    root: string;
+    force?: boolean;
+    configAnswers?: ConfigAnswers;
+    configFile?: string;
+};
+/** Per-request browser settings. `cookies` are set before the page loads. */
+type PageOptions = {
+    cookies?: Record<string, string>;
+};
+/** Takes a screenshot of url at a viewport width and returns the PNG. Injected by the CLI. */
+type Shooter = (url: string, width: number, options?: PageOptions) => Promise<Buffer>;
+/** What convert needs from outside: a logger, a command runner, the app's config, for the baseline a shooter, and an interrupt signal. */
+type ConvertIo = {
+    log: (s: string) => void;
+    shoot?: Shooter;
+    run: (cmd: string, cwd: string) => Promise<{
+        code: number;
+        out: string;
+    }>;
+    config: ConvertConfig;
+    /** Fires when the person interrupts the run. Convert checks it after slow steps and rolls back. */
+    signal?: AbortSignal;
+};
+/** The passes that make edits, plus wiring. */
+type EditKind = 'tailwind' | 'css' | 'markup' | 'strings' | 'formats' | 'wiring';
+/** What a phase 1 run changed and left to finish. */
+type ConvertSummary = {
+    branch: string;
+    filesChanged: number;
+    edits: number;
+    /** Applied edits per pass. Wiring counts its edits plus the files it wrote. */
+    byKind: Record<EditKind, number>;
+    /** Files with applied edits, at post-move paths, sorted by file. */
+    changed: {
+        file: string;
+        edits: number;
+    }[];
+    flags: Flag[];
+    strings: number;
+    skipped: {
+        file: string;
+        reason: string;
+    }[];
+};
+/** Saved to `.dualkit/convert.json`. `generated` lists the files convert wrote, which later runs leave alone. */
+type ConvertState = {
+    mode: Mode;
+    base: string;
+    branch: string;
+    framework: Project['framework'];
+    phase: 'converted' | 'finished';
+    generated: string[];
+};
+
+/** Thrown when two edits touch the same span. */
+declare class OverlapError extends Error {
+    readonly first: Edit;
+    readonly second: Edit;
+    constructor(first: Edit, second: Edit);
+}
+/**
+ * Applies non-overlapping edits in any order. Edits that start at the same offset apply in their given
+ * order, so an insert listed before a replacement at that offset lands before it. Throws on an edit
+ * outside the text.
+ */
+declare function applyEdits(text: string, edits: Edit[]): string;
+
+/** Thrown when the app is not one convert can handle. The message names what is supported. */
+declare class UnsupportedError extends Error {
+    constructor(message: string);
+}
+/** Reads the app at root and says which framework, entry, styling and tooling it uses. Throws UnsupportedError for anything else. */
+declare function detectProject(root: string): Project;
+
+/** The branch a mode converts on. */
+declare const branchFor: (mode: Mode) => string;
+/** The flags a person or agent still has to act on. Info flags are kept in the summary but are never problems. */
+declare const problems: (flags: readonly Flag[]) => Flag[];
+/**
+ * Phase 1: converts the app at `options.root` on the branch `dualkit/<mode>` and commits it with the
+ * person's own git identity. Transforms run in memory first, so a refusal changes nothing. A re-run on
+ * a branch convert already converted runs again in place and commits only when something changed.
+ */
+declare function convert(options: ConvertOptions, ioIn: ConvertIo): Promise<ConvertSummary>;
+
+/** Thrown when convert will not start. The message is one line saying why. */
+declare class RefusedError extends Error {
+    constructor(message: string);
+}
+
+/** Thrown when a run fails after the branch was created. The message names the step and where the repo now is. */
+declare class ConvertFailedError extends Error {
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+
+/** What phase 2 needs from outside: phase 1's io plus an accessibility audit and a lint count. */
+type FinishIo = ConvertIo & {
+    audit: (url: string, width: number, options?: PageOptions) => Promise<{
+        score: number;
+        errors: number;
+        warnings: number;
+    }>;
+    lint: (root: string) => Promise<number>;
+};
+/**
+ * Phase 2: writes the messages from the ledger, serves the app, checks English against the baseline and
+ * audits the Arabic pages, writes dualkit-convert.md and commits it with the messages and the ledger.
+ * When a step fails after writing starts, finish puts its own files back and commits nothing.
+ */
+declare function finish(options: FinishOptions, ioIn: FinishIo): Promise<{
+    reportPath: string;
+    passed: boolean;
+}>;
+
+export { type ConfigAnswers, type ConvertConfig, ConvertFailedError, type ConvertIo, type ConvertOptions, type ConvertState, type ConvertSummary, type Edit, type FileResult, type FinishIo, type FinishOptions, type Flag, type FlagKind, type Mode, OverlapError, type Project, RefusedError, type Shooter, UnsupportedError, applyEdits, branchFor, convert, detectProject, finish, problems };