@appeeky/spec 0.0.0-stage → 0.1.0

package/dist/files.js

@@ -0,0 +1,129 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import YAML from "yaml";
+import { appStoreListingSchema, fieldsFor, googlePlayListingSchema, specFileSchema, STORES, } from "./schema.js";
+export const SPEC_FILE = "appeeky.spec.yaml";
+export const SPEC_DIR = "appeeky";
+export class SpecError extends Error {
+    file;
+    constructor(message, file) {
+        super(file ? `${file}: ${message}` : message);
+        this.file = file;
+        this.name = "SpecError";
+    }
+}
+export function listingsDir(root, store) {
+    return join(root, SPEC_DIR, "store", store);
+}
+export function listingPath(root, store, locale) {
+    return join(listingsDir(root, store), `${locale}.yaml`);
+}
+/** Walk up from `start` to the folder that holds `appeeky.spec.yaml`. */
+export function findRoot(start = process.cwd()) {
+    let dir = resolve(start);
+    for (;;) {
+        if (existsSync(join(dir, SPEC_FILE)))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+function parse(schema, raw, file) {
+    const result = schema.safeParse(raw ?? {});
+    if (!result.success) {
+        const detail = result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+        throw new SpecError(detail, file);
+    }
+    return result.data;
+}
+async function readYaml(file) {
+    const text = await readFile(file, "utf8");
+    try {
+        return YAML.parse(text);
+    }
+    catch (err) {
+        throw new SpecError(err.message, file);
+    }
+}
+export function parseSpec(raw, file = SPEC_FILE) {
+    return parse(specFileSchema, raw, file);
+}
+export function parseListing(store, raw, file) {
+    return store === "app-store" ? parse(appStoreListingSchema, raw, file) : parse(googlePlayListingSchema, raw, file);
+}
+/** Load the spec and every listing file under `appeeky/store/`. */
+export async function loadProject(start) {
+    const root = findRoot(start);
+    if (!root)
+        throw new SpecError(`No ${SPEC_FILE} found here or in a parent folder. Run \`appeeky-spec init\` first.`);
+    const spec = parseSpec(await readYaml(join(root, SPEC_FILE)), join(root, SPEC_FILE));
+    const project = { root, spec, listings: { "app-store": {}, "google-play": {} } };
+    for (const store of STORES) {
+        const dir = listingsDir(root, store);
+        if (!existsSync(dir))
+            continue;
+        const files = (await readdir(dir)).filter((f) => f.endsWith(".yaml") || f.endsWith(".yml")).sort();
+        for (const f of files) {
+            const locale = f.replace(/\.ya?ml$/, "");
+            const file = join(dir, f);
+            project.listings[store][locale] = parseListing(store, await readYaml(file), file);
+        }
+    }
+    return project;
+}
+/** Keep the store's field order and use block scalars for multi-line text so diffs stay readable. */
+export function stringifyListing(store, listing) {
+    const ordered = {};
+    for (const field of fieldsFor(store)) {
+        const value = listing[field];
+        if (value !== undefined)
+            ordered[field] = value;
+    }
+    return YAML.stringify(ordered, { lineWidth: 0, blockQuote: "literal" });
+}
+export async function writeListing(root, store, locale, listing) {
+    const file = listingPath(root, store, locale);
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, stringifyListing(store, listing));
+    return file;
+}
+export function stringifySpec(spec) {
+    // Optional sections stay out of the file until they have content.
+    const clean = { ...spec };
+    for (const k of ["storefronts", "personas"]) {
+        const v = clean[k];
+        if (v === undefined || (Array.isArray(v) ? v.length === 0 : Object.keys(v).length === 0))
+            delete clean[k];
+    }
+    const doc = new YAML.Document(clean);
+    doc.commentBefore =
+        " Appeeky Spec: your app's store presence as a spec.\n Docs: https://github.com/appeeky/appeeky-spec";
+    return doc.toString({ lineWidth: 0 });
+}
+export async function writeSpec(root, spec) {
+    const file = join(root, SPEC_FILE);
+    await writeFile(file, stringifySpec(spec));
+    return file;
+}
+const PULL_STATE = join(".appeeky", "pulled.json");
+export async function readPullState(root) {
+    const file = join(root, PULL_STATE);
+    if (!existsSync(file))
+        return {};
+    try {
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export async function recordPull(root, store, target) {
+    const state = { ...(await readPullState(root)), [store]: { target, at: new Date().toISOString() } };
+    const file = join(root, PULL_STATE);
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, `${JSON.stringify(state, null, 2)}\n`);
+}
+//# sourceMappingURL=files.js.map

package/dist/history.d.ts

@@ -0,0 +1,43 @@
+import type { StoreId } from "./schema.js";
+import type { FieldChange } from "./stores/types.js";
+import { type MetricsCheck } from "./metrics.js";
+import type { ConversionChange, RankEvaluation, RankSnapshot } from "./verify.js";
+/**
+ * Every push writes a release record to `appeeky/releases/`. It is the
+ * history of what went live and when, the input for measuring impact later,
+ * and what a revert pushes back.
+ */
+export interface ReleaseRecord {
+    id: string;
+    pushedAt: string;
+    store: StoreId;
+    /** Where it went, e.g. "version 2.4 (prepare for submission)". */
+    target: string;
+    via: string;
+    /** Free-text reason or hypothesis, from `push --note`. */
+    note?: string;
+    changes: Array<Pick<FieldChange, "locale" | "field" | "before" | "after">>;
+    /** Search ranks of the targets right before the push. */
+    baseline?: {
+        at: string;
+        source: string;
+        ranks: RankSnapshot;
+    };
+    /** Rank checks after the push (`appeeky-spec verify`). */
+    checks?: Array<{
+        at: string;
+        day: number;
+        ranks: RankSnapshot;
+        conversion?: ConversionChange;
+        metrics?: MetricsCheck;
+    } & RankEvaluation>;
+}
+/** Days since a release went out. */
+export declare function releaseAge(record: ReleaseRecord, now?: Date): number;
+/** Markdown summary of a release: for PR descriptions, changelogs and team updates. */
+export declare function releaseMarkdown(record: ReleaseRecord): string;
+export declare function releasesDir(root: string): string;
+export declare function releaseId(date: Date, store: StoreId): string;
+export declare function writeRelease(root: string, record: ReleaseRecord): Promise<string>;
+export declare function updateRelease(root: string, record: ReleaseRecord): Promise<void>;
+export declare function readReleases(root: string): Promise<ReleaseRecord[]>;

package/dist/history.js

@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import YAML from "yaml";
+import { SPEC_DIR } from "./files.js";
+import { formatChange } from "./metrics.js";
+/** Days since a release went out. */
+export function releaseAge(record, now = new Date()) {
+    return Math.floor((now.getTime() - Date.parse(record.pushedAt)) / 86_400_000);
+}
+/** Markdown summary of a release: for PR descriptions, changelogs and team updates. */
+export function releaseMarkdown(record) {
+    const lines = [`### ${record.store === "app-store" ? "App Store" : "Google Play"} · ${record.target}`];
+    if (record.note)
+        lines.push("", `> ${record.note}`);
+    lines.push("", "| Locale | Field | Before | After |", "| --- | --- | --- | --- |");
+    const cell = (v) => (v ?? "").replace(/\n+/g, " ").replace(/\|/g, "\\|").slice(0, 80) || "—";
+    for (const c of record.changes)
+        lines.push(`| ${c.locale} | ${c.field} | ${cell(c.before)} | ${cell(c.after)} |`);
+    const last = record.checks?.at(-1);
+    if (last) {
+        const conv = last.conversion ? `, conversion ${(last.conversion.before.rate * 100).toFixed(1)}% → ${(last.conversion.after.rate * 100).toFixed(1)}%` : "";
+        lines.push("", `Day ${last.day}: **${last.verdict}** (${last.improved.length} up, ${last.dropped.length} down, ${last.regressions.length} top-20 lost${conv})`);
+        for (const m of last.metrics?.changes ?? [])
+            lines.push(`- ${formatChange(m, last.metrics?.after.currency)}`);
+    }
+    return lines.join("\n");
+}
+export function releasesDir(root) {
+    return join(root, SPEC_DIR, "releases");
+}
+export function releaseId(date, store) {
+    return `${date.toISOString().replace(/[:.]/g, "-").replace(/-\d{3}Z$/, "Z")}-${store}`;
+}
+export async function writeRelease(root, record) {
+    const dir = releasesDir(root);
+    await mkdir(dir, { recursive: true });
+    const file = join(dir, `${record.id}.yaml`);
+    await writeFile(file, YAML.stringify(record, { lineWidth: 0, blockQuote: "literal" }));
+    return file;
+}
+export async function updateRelease(root, record) {
+    await writeFile(join(releasesDir(root), `${record.id}.yaml`), YAML.stringify(record, { lineWidth: 0, blockQuote: "literal" }));
+}
+export async function readReleases(root) {
+    const dir = releasesDir(root);
+    if (!existsSync(dir))
+        return [];
+    const files = (await readdir(dir)).filter((f) => f.endsWith(".yaml")).sort().reverse();
+    const out = [];
+    for (const f of files)
+        out.push(YAML.parse(await readFile(join(dir, f), "utf8")));
+    return out;
+}
+//# sourceMappingURL=history.js.map

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+export * from "./schema.js";
+export * from "./limits.js";
+export * from "./text.js";
+export * from "./lint.js";
+export * from "./coverage.js";
+export * from "./storefronts.js";
+export * from "./diff.js";
+export * from "./files.js";
+export * from "./history.js";
+export * from "./transport.js";
+export * from "./project.js";
+export * from "./appeeky-api.js";
+export * from "./suggest.js";
+export * from "./verify.js";
+export * from "./measure.js";
+export * from "./metrics.js";
+export * from "./experiments.js";
+export * from "./screenshots.js";
+export * from "./report.js";
+export * from "./category.js";
+export * from "./visibility.js";
+export type { FieldChange, PushResult, RemoteState, StoreAdapter } from "./stores/types.js";
+export { AppStoreAdapter, type AppStoreContext } from "./stores/app-store.js";
+export { GooglePlayAdapter } from "./stores/google-play.js";

package/dist/index.js

@@ -0,0 +1,24 @@
+export * from "./schema.js";
+export * from "./limits.js";
+export * from "./text.js";
+export * from "./lint.js";
+export * from "./coverage.js";
+export * from "./storefronts.js";
+export * from "./diff.js";
+export * from "./files.js";
+export * from "./history.js";
+export * from "./transport.js";
+export * from "./project.js";
+export * from "./appeeky-api.js";
+export * from "./suggest.js";
+export * from "./verify.js";
+export * from "./measure.js";
+export * from "./metrics.js";
+export * from "./experiments.js";
+export * from "./screenshots.js";
+export * from "./report.js";
+export * from "./category.js";
+export * from "./visibility.js";
+export { AppStoreAdapter } from "./stores/app-store.js";
+export { GooglePlayAdapter } from "./stores/google-play.js";
+//# sourceMappingURL=index.js.map

package/dist/limits.d.ts

@@ -0,0 +1,15 @@
+import type { StoreId } from "./schema.js";
+export interface FieldLimit {
+    max: number;
+    /** Characters as App Store Connect counts them (a Cyrillic or CJK letter is one). */
+    unit: "chars";
+}
+export declare const LIMITS: Record<StoreId, Record<string, FieldLimit>>;
+/**
+ * Fields that go live without a new app version. On the App Store only the
+ * promotional text changes on the live version; everything else waits for the
+ * next version you submit.
+ */
+export declare const LIVE_EDITABLE: Record<StoreId, ReadonlySet<string>>;
+/** Fields the store indexes for search. */
+export declare const INDEXED_FIELDS: Record<StoreId, readonly string[]>;

package/dist/limits.js

@@ -0,0 +1,30 @@
+export const LIMITS = {
+    "app-store": {
+        name: { max: 30, unit: "chars" },
+        subtitle: { max: 30, unit: "chars" },
+        keywords: { max: 100, unit: "chars" },
+        promotionalText: { max: 170, unit: "chars" },
+        description: { max: 4000, unit: "chars" },
+        whatsNew: { max: 4000, unit: "chars" },
+    },
+    "google-play": {
+        title: { max: 30, unit: "chars" },
+        shortDescription: { max: 80, unit: "chars" },
+        fullDescription: { max: 4000, unit: "chars" },
+    },
+};
+/**
+ * Fields that go live without a new app version. On the App Store only the
+ * promotional text changes on the live version; everything else waits for the
+ * next version you submit.
+ */
+export const LIVE_EDITABLE = {
+    "app-store": new Set(["promotionalText"]),
+    "google-play": new Set(["title", "shortDescription", "fullDescription", "video"]),
+};
+/** Fields the store indexes for search. */
+export const INDEXED_FIELDS = {
+    "app-store": ["name", "subtitle", "keywords"],
+    "google-play": ["title", "shortDescription", "fullDescription"],
+};
+//# sourceMappingURL=limits.js.map

package/dist/lint.d.ts

@@ -0,0 +1,16 @@
+import type { AppStoreListing, GooglePlayListing, Project, StoreId } from "./schema.js";
+export type Severity = "error" | "warning" | "info";
+export interface Issue {
+    severity: Severity;
+    /** Stable rule id, e.g. `limit`, `keywords/duplicate-of-name`. */
+    rule: string;
+    store: StoreId;
+    locale: string;
+    field?: string;
+    message: string;
+}
+export declare function lintLength(store: StoreId, locale: string, field: string, value: string | undefined): Issue[];
+export declare function lintAppStore(locale: string, listing: AppStoreListing): Issue[];
+export declare function lintGooglePlay(locale: string, listing: GooglePlayListing): Issue[];
+export declare function lintProject(project: Project): Issue[];
+export declare function hasErrors(issues: Issue[]): boolean;

package/dist/lint.js

@@ -0,0 +1,159 @@
+import { LIMITS } from "./limits.js";
+import { charLength, isEnglish, keywordEntries, singular, unique, words } from "./text.js";
+/** Words Apple already ignores or that buy nothing in the keyword field. */
+const APPLE_FILLER = new Set(["app", "apps", "the", "a", "an", "and", "or", "for", "with", "of", "iphone", "ipad"]);
+/** Google Play's metadata policy rejects these in the title. */
+const PLAY_TITLE_BANNED = [/\bbest\b/i, /#\s?1\b/, /\btop\b/i, /\bfree\b/i, /\bno\.?\s?1\b/i, /\bsale\b/i, /\bdiscount\b/i];
+export function lintLength(store, locale, field, value) {
+    const limit = LIMITS[store][field];
+    if (!limit || value === undefined)
+        return [];
+    const used = charLength(value);
+    if (used <= limit.max)
+        return [];
+    return [
+        {
+            severity: "error",
+            rule: "limit",
+            store,
+            locale,
+            field,
+            message: `${field} is ${used}/${limit.max} characters; the store rejects it.`,
+        },
+    ];
+}
+export function lintAppStore(locale, listing) {
+    const issues = [];
+    const at = (severity, rule, field, message) => issues.push({ severity, rule, store: "app-store", locale, field, message });
+    for (const [field, value] of Object.entries(listing)) {
+        issues.push(...lintLength("app-store", locale, field, value));
+    }
+    const nameWords = new Set(words(listing.name));
+    const subtitleWords = words(listing.subtitle);
+    const repeatedInSubtitle = unique(subtitleWords.filter((w) => nameWords.has(w)));
+    if (repeatedInSubtitle.length > 0) {
+        at("warning", "subtitle/repeats-name", "subtitle", `Subtitle repeats ${quoteList(repeatedInSubtitle)} from the name. Each word is indexed once, so use the space for a new word.`);
+    }
+    if (listing.keywords !== undefined) {
+        const field = listing.keywords;
+        if (/,\s+|\s+,/.test(field)) {
+            at("warning", "keywords/spaces", "keywords", "Spaces around commas waste characters in the keyword field. Write `a,b,c`.");
+        }
+        const entries = keywordEntries(field);
+        if (entries.length === 1 && words(entries[0]).length >= 4) {
+            at("warning", "keywords/no-commas", "keywords", "The keyword field has no commas, so it reads as one long phrase. Separate keywords with commas: `a,b,c`.");
+        }
+        const seen = new Map();
+        for (const entry of entries)
+            seen.set(entry.toLowerCase(), (seen.get(entry.toLowerCase()) ?? 0) + 1);
+        const repeated = [...seen].filter(([, n]) => n > 1).map(([e]) => e);
+        if (repeated.length > 0) {
+            at("warning", "keywords/duplicate", "keywords", `The keyword field lists ${quoteList(repeated)} more than once.`);
+        }
+        const keywordWords = entries.flatMap((e) => words(e));
+        const titled = new Set([...nameWords, ...subtitleWords]);
+        const alreadyIndexed = unique(keywordWords.filter((w) => titled.has(w)));
+        if (alreadyIndexed.length > 0) {
+            at("warning", "keywords/duplicate-of-name", "keywords", `${quoteList(alreadyIndexed)} already ${alreadyIndexed.length === 1 ? "appears" : "appear"} in the name or subtitle, so the keyword field does not need ${alreadyIndexed.length === 1 ? "it" : "them"}.`);
+        }
+        const repeatedWords = unique(keywordWords.filter((w, i) => keywordWords.indexOf(w) !== i));
+        if (repeatedWords.length > 0) {
+            at("info", "keywords/repeated-word", "keywords", `${quoteList(repeatedWords)} ${repeatedWords.length === 1 ? "is" : "are"} written more than once. Single words combine with each other, so phrases rarely need repeating.`);
+        }
+        if (isEnglish(locale)) {
+            const filler = unique(keywordWords.filter((w) => APPLE_FILLER.has(w)));
+            if (filler.length > 0) {
+                at("info", "keywords/filler", "keywords", `${quoteList(filler)} add little in the keyword field.`);
+            }
+            const all = unique([...titled, ...keywordWords]);
+            const plurals = all.filter((w) => singular(w) !== w && all.includes(singular(w)));
+            if (plurals.length > 0) {
+                at("info", "keywords/plural-pair", "keywords", `Both singular and plural forms are used (${quoteList(plurals.map((p) => `${singular(p)}/${p}`))}). One form is often enough.`);
+            }
+        }
+        const spare = 100 - charLength(field);
+        if (spare >= 10) {
+            at("info", "keywords/unused-space", "keywords", `${spare} characters of the keyword field are unused.`);
+        }
+    }
+    if (listing.name !== undefined && listing.name.trim() === "")
+        at("error", "required", "name", "The name cannot be empty.");
+    return issues;
+}
+export function lintGooglePlay(locale, listing) {
+    const issues = [];
+    for (const [field, value] of Object.entries(listing)) {
+        issues.push(...lintLength("google-play", locale, field, value));
+    }
+    if (listing.title !== undefined) {
+        const banned = PLAY_TITLE_BANNED.filter((re) => re.test(listing.title)).map((re) => listing.title.match(re)[0]);
+        if (banned.length > 0) {
+            issues.push({
+                severity: "warning",
+                rule: "play/title-policy",
+                store: "google-play",
+                locale,
+                field: "title",
+                message: `Google Play's metadata policy does not allow ranking or promotional words such as ${quoteList(banned)} in the title (fine only when part of your brand).`,
+            });
+        }
+        if (/\p{Extended_Pictographic}/u.test(listing.title)) {
+            issues.push({
+                severity: "error",
+                rule: "play/title-emoji",
+                store: "google-play",
+                locale,
+                field: "title",
+                message: "Google Play does not allow emoji in the title.",
+            });
+        }
+        const letters = listing.title.replace(/[^\p{L}]/gu, "");
+        if (letters.length >= 6 && letters === letters.toUpperCase() && letters !== letters.toLowerCase()) {
+            issues.push({
+                severity: "warning",
+                rule: "play/title-caps",
+                store: "google-play",
+                locale,
+                field: "title",
+                message: "An all-caps title is against Google Play's metadata policy unless it is your brand.",
+            });
+        }
+    }
+    return issues;
+}
+export function lintProject(project) {
+    const issues = [];
+    for (const [locale, listing] of Object.entries(project.listings["app-store"]))
+        issues.push(...lintAppStore(locale, listing));
+    for (const [locale, listing] of Object.entries(project.listings["google-play"]))
+        issues.push(...lintGooglePlay(locale, listing));
+    if (project.spec.stores.appStore && Object.keys(project.listings["app-store"]).length === 0) {
+        issues.push({
+            severity: "info",
+            rule: "listings/empty",
+            store: "app-store",
+            locale: "*",
+            message: "No App Store listings yet. Run `appeeky-spec pull` to start from the live store.",
+        });
+    }
+    if (project.spec.stores.googlePlay && Object.keys(project.listings["google-play"]).length === 0) {
+        issues.push({
+            severity: "info",
+            rule: "listings/empty",
+            store: "google-play",
+            locale: "*",
+            message: "No Google Play listings yet. Run `appeeky-spec pull` to start from the live store.",
+        });
+    }
+    return issues;
+}
+export function hasErrors(issues) {
+    return issues.some((i) => i.severity === "error");
+}
+function quoteList(items) {
+    const quoted = items.map((i) => `"${i}"`);
+    if (quoted.length <= 1)
+        return quoted.join("");
+    return `${quoted.slice(0, -1).join(", ")} and ${quoted.at(-1)}`;
+}
+//# sourceMappingURL=lint.js.map

package/dist/loops.d.ts

@@ -0,0 +1,37 @@
+import { type Experiment } from "./experiments.js";
+import { type ReleaseRecord } from "./history.js";
+import type { StoreId } from "./schema.js";
+/** A check this many days past its date with no result has stalled (CI not running, a key missing). */
+export declare const LATE_AFTER_DAYS = 2;
+/** Fewer installs than this in a window: the numbers are a hint, not a result. */
+export declare const FEW_INSTALLS = 100;
+export type LoopState = "measuring" | "due" | "late" | "closed";
+export interface Loop {
+    kind: "release" | "experiment";
+    id: string;
+    store?: StoreId;
+    /** What changed, or the hypothesis. */
+    what: string;
+    /** What decides it. */
+    metric: string;
+    startedAt: string;
+    /** Next check date (YYYY-MM-DD), none once closed. */
+    nextCheck?: string;
+    state: LoopState;
+    /** The latest result: "day 7 won", "won (12 ≥ 10)". */
+    result?: string;
+    /** The numbers behind the latest result. */
+    detail?: string[];
+    warnings: string[];
+}
+export declare function releaseLoop(r: ReleaseRecord, now?: Date): Loop;
+export declare function experimentLoop(e: Experiment, now?: Date): Loop;
+export declare function collectLoops(root: string, now?: Date): Promise<Loop[]>;
+/** appeeky/loops.md: what is being measured, what is due, what came out. Rewritten, not appended. */
+export declare function loopsMarkdown(loops: Loop[], now?: Date): string;
+export declare function writeLoops(root: string, now?: Date): Promise<Loop[]>;
+/**
+ * Stores with no release being measured: a new listing change there will not mix with an
+ * open one. This is what a scheduled agent checks before it proposes anything.
+ */
+export declare function freeStores(loops: Loop[], stores: StoreId[]): StoreId[];