@stag-build/phonebook 0.1.3 → 0.1.4

package/dist/scan/scope.js

@@ -0,0 +1,208 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { realpath } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import { computeStats } from './stats.js';
+import { componentsNamedIn } from './ios.js';
+const run = promisify(execFile);
+/**
+ * Narrow a finished report to the components declared in `paths`.
+ *
+ * The scan itself is never narrowed, and that distinction is the whole design.
+ * Which types are enums, what a project's preview helper supplies, which
+ * locales ship — all of it is a fact about the project, not about one file, and
+ * a scan that walked only the changed files would get every one of them wrong.
+ * So the walk stays whole and the report is filtered afterwards, which costs a
+ * few hundred milliseconds and buys an answer that is still correct.
+ *
+ * What it saves is the reader. A run that touched five components was handed
+ * five hundred gaps, of which ten were its own; the rest are a backlog nobody
+ * asked it about, and an agent cannot tell which is which.
+ */
+export function scopeReport(report, paths) {
+    if (paths.length === 0)
+        return report;
+    const wanted = paths.map((p) => p.replace(/^\.\//, '').replace(/\/+$/, ''));
+    const matches = (file) => wanted.some((p) => file === p || file.startsWith(`${p}/`));
+    const components = report.components.filter((c) => matches(c.file));
+    const orphanPreviews = report.orphanPreviews.filter((p) => matches(p.file));
+    const changed = new Set(components.map((c) => c.name));
+    const previewsOfWhatChanged = previewsRendering(report, changed, matches);
+    const uncoveredUsesOfWhatChanged = uncoveredUses(report, changed, matches);
+    return {
+        ...report,
+        components,
+        orphanPreviews,
+        stats: computeStats(components, orphanPreviews),
+        scope: {
+            paths: wanted,
+            componentsScanned: report.components.length,
+            ...(previewsOfWhatChanged.length > 0 ? { previewsOfWhatChanged } : {}),
+            ...(uncoveredUsesOfWhatChanged.length > 0 ? { uncoveredUsesOfWhatChanged } : {}),
+        },
+    };
+}
+/**
+ * Previews outside the scope that put something inside it on screen.
+ *
+ * A component is rarely previewed only where it is declared: edit a row and the
+ * preview that shows it may live in the list's file, which the filter drops. The
+ * agent can read these and decide — they are as likely to be fine as not.
+ *
+ * Reached through the component graph rather than the preview's own text,
+ * because a preview usually names one view and shows a dozen. IceCubes made
+ * the point: changing `StatusRowDetailView` matched no preview at all, because
+ * the one preview that renders it says `StatusRowView(` and nothing else — the
+ * detail view is three levels down its body. Matching the text alone answers a
+ * question nobody asked, which is which previews mention a name.
+ */
+function previewsRendering(report, changed, inScope) {
+    const found = [];
+    const previews = [...report.components.flatMap((c) => c.previews), ...report.orphanPreviews];
+    const known = new Set(report.components.map((c) => c.name));
+    // Guarded children are left to the ask list below. A preview that reaches
+    // something only through an `if` has not been shown to render it, and saying
+    // both here and there would be two answers to one question.
+    const uses = new Map(report.components.map((c) => {
+        const guarded = new Set((c.conditionalUses ?? []).map((u) => u.name));
+        return [c.name, (c.uses ?? []).filter((n) => !guarded.has(n))];
+    }));
+    for (const preview of previews) {
+        if (inScope(preview.file))
+            continue;
+        const renders = reachedFrom(componentsNamedIn(preview.annotationText ?? '', known), uses, changed);
+        if (renders.length === 0)
+            continue;
+        found.push({ name: preview.displayName ?? preview.name, file: preview.file, line: preview.line, renders });
+    }
+    return found;
+}
+/**
+ * Which of `targets` are reachable from `seeds` by following `uses`.
+ *
+ * A view tree, walked breadth-first. `seen` is what keeps a cycle — two views
+ * that render each other under different conditions, which SwiftUI allows —
+ * from being an infinite descent.
+ */
+function reachedFrom(seeds, uses, targets) {
+    const hit = new Set();
+    const seen = new Set();
+    const queue = [...seeds];
+    while (queue.length > 0) {
+        const name = queue.shift();
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        if (targets.has(name))
+            hit.add(name);
+        queue.push(...(uses.get(name) ?? []));
+    }
+    return [...hit];
+}
+/**
+ * Views outside the scope that render something inside it and have no preview
+ * of their own.
+ *
+ * Two ways to end up here, and the second is the one that took two runs against
+ * IceCubes to see. A view with no preview at all shows the change nowhere. A
+ * view that renders it inside an `if` has a preview that may show nothing of it
+ * either — StatusRowView is previewed as a timeline row, and the detail view it
+ * was changed to render only appears when focused. "Has a preview" answered the
+ * wrong question, and answered it yes.
+ *
+ * Whether either context deserves a preview is a judgment about the product,
+ * which is why this is something to ask the designer rather than a gap to
+ * close.
+ *
+ * Direct users only, unlike the list above, and the asymmetry is the point. A
+ * fact can be long and still be worth reading; a question cannot. Follow the
+ * graph from a component every screen shows and the ask list becomes every
+ * screen in the app, which is not something anyone can answer.
+ */
+function uncoveredUses(report, changed, inScope) {
+    const found = [];
+    for (const component of report.components) {
+        if (inScope(component.file))
+            continue;
+        const uses = (component.uses ?? []).filter((name) => changed.has(name));
+        if (uses.length === 0)
+            continue;
+        if (component.previews.length === 0) {
+            found.push({ component: component.name, file: component.file, line: component.line, uses, reason: 'no-preview' });
+            continue;
+        }
+        // It has a preview. That only settles the question for what it shows
+        // unconditionally.
+        const guarded = (component.conditionalUses ?? []).filter((u) => changed.has(u.name));
+        if (guarded.length === 0)
+            continue;
+        // The first guarded render carries the line and the condition. Listing one
+        // condition per child would make the question longer than the answer, and
+        // the reader opens the file either way.
+        found.push({
+            component: component.name,
+            file: component.file,
+            line: guarded[0].line,
+            uses: guarded.map((u) => u.name),
+            reason: 'conditional',
+            guard: guarded[0].guard,
+            previews: component.previews.map((p) => ({
+                name: p.displayName ?? p.name,
+                file: p.file,
+                line: p.line,
+            })),
+        });
+    }
+    return found;
+}
+/**
+ * Files with uncommitted changes, relative to the project directory.
+ *
+ * `git status --porcelain` reports staged, unstaged and untracked in one pass,
+ * which is what an agent's turn leaves behind: it edits and adds, it does not
+ * commit. Paths come back relative to the repository root, so they are rebased
+ * onto the project directory — the two differ whenever phonebook.config.json
+ * sits in a subdirectory of a larger repository.
+ *
+ * A directory that is not a repository, or a git that is not installed, is not
+ * an error here. It means the caller cannot scope by change and gets the whole
+ * project, which is the behaviour they had before asking.
+ */
+export async function changedFiles(projectDir) {
+    let root;
+    let status;
+    let base;
+    try {
+        root = (await run('git', ['rev-parse', '--show-toplevel'], { cwd: projectDir })).stdout.trim();
+        status = (await run('git', ['status', '--porcelain'], { cwd: projectDir })).stdout;
+        // git answers in real paths. The caller's directory may be reached through
+        // a symlink — every macOS temp directory is — and comparing the two
+        // unresolved puts the whole repository outside itself.
+        base = await realpath(projectDir);
+    }
+    catch {
+        return [];
+    }
+    const files = new Set();
+    for (const line of status.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        // "XY path", or "XY old -> new" for a rename: the new name is the one that
+        // still exists to be scanned.
+        let path = line.slice(3);
+        const arrow = path.indexOf(' -> ');
+        if (arrow !== -1)
+            path = path.slice(arrow + 4);
+        path = path.trim().replace(/^"|"$/g, '');
+        if (path === '')
+            continue;
+        const fromProject = relative(base, resolve(root, path));
+        // Outside the project directory: another module of the same repository,
+        // which this scan never walked and cannot report on.
+        if (fromProject.startsWith('..'))
+            continue;
+        files.add(fromProject);
+    }
+    return [...files];
+}
+//# sourceMappingURL=scope.js.map

package/dist/scan/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../src/scan/scope.ts"],"names":[],"mappings":"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"}

package/dist/scan/stats.d.ts

@@ -0,0 +1,12 @@
+import type { ScannedComponent, ScannedPreview, CoverageReport } from './types.js';
+/**
+ * Totals over a set of components and the previews that could not be matched
+ * to one.
+ *
+ * Shared by both scanners and by `scopeReport`, which needs the same numbers
+ * over a subset. The self-preview rule is Android's — a composable annotated
+ * with `@Preview` is its own preview — and it costs nothing on iOS, where
+ * `#Preview` is always a separate top-level block and the count is therefore
+ * always zero.
+ */
+export declare function computeStats(components: ScannedComponent[], orphanPreviews: ScannedPreview[]): CoverageReport['stats'];

package/dist/scan/stats.js

@@ -0,0 +1,24 @@
+/**
+ * Totals over a set of components and the previews that could not be matched
+ * to one.
+ *
+ * Shared by both scanners and by `scopeReport`, which needs the same numbers
+ * over a subset. The self-preview rule is Android's — a composable annotated
+ * with `@Preview` is its own preview — and it costs nothing on iOS, where
+ * `#Preview` is always a separate top-level block and the count is therefore
+ * always zero.
+ */
+export function computeStats(components, orphanPreviews) {
+    const allPreviews = [...components.flatMap((c) => c.previews), ...orphanPreviews];
+    return {
+        components: components.length,
+        withPreview: components.filter((c) => c.previews.length > 0).length,
+        withDarkPreview: components.filter((c) => c.previews.some((p) => p.dark)).length,
+        totalPreviews: components.reduce((sum, c) => sum + c.previews.length, 0) + orphanPreviews.length,
+        hintCount: allPreviews.reduce((sum, p) => sum + (p.hints?.length ?? 0), 0),
+        gapCount: components.reduce((sum, c) => sum + (c.gaps?.length ?? 0), 0),
+        componentsWithGaps: components.filter((c) => (c.gaps ?? []).some((g) => g.severity === 'warning')).length,
+        selfPreviewed: components.filter((c) => c.previews.some((p) => p.name === c.name && p.line === c.line)).length,
+    };
+}
+//# sourceMappingURL=stats.js.map

package/dist/scan/stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.js","sourceRoot":"","sources":["../../src/scan/stats.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,UAA8B,EAC9B,cAAgC;IAEhC,MAAM,WAAW,GAAG,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,GAAG,cAAc,CAAC,CAAC;IAClF,OAAO;QACL,UAAU,EAAE,UAAU,CAAC,MAAM;QAC7B,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,MAAM;QACnE,eAAe,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM;QAChF,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,cAAc,CAAC,MAAM;QAChG,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;QAC1E,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;QACvE,kBAAkB,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAC1C,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CACrD,CAAC,MAAM;QACR,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CACrC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC,CAC/D,CAAC,MAAM;KACT,CAAC;AACJ,CAAC"}

package/dist/scan/types.d.ts

@@ -4,7 +4,8 @@
  * can find components with missing previews/states and add them as code.
  */
 import type { PreviewHint } from './hints.js';
-export type { PreviewHint };
+import type { ComponentProperty, CoverageGap } from './gaps.js';
+export type { PreviewHint, ComponentProperty, CoverageGap };
 export interface ScannedPreview {
     /** Preview function name (Android) or #Preview display name / "unnamed" (iOS) */
     name: string;
@@ -25,6 +26,22 @@ export interface ScannedPreview {
      * annotation doesn't declare. See src/scan/hints.ts. */
     hints?: PreviewHint[];
 }
+/**
+ * A component rendered only behind a condition, and enough about the render to
+ * go and look at it.
+ *
+ * The condition text is the payload. "Renders it inside an if" names a shape;
+ * `if isFocused, !isCompact` names the state a preview would have to set, which
+ * is the difference between a question and a chore.
+ */
+export interface ConditionalUse {
+    /** The component rendered behind the condition. */
+    name: string;
+    /** The condition as written, whitespace collapsed. */
+    guard: string;
+    /** Line of the guarded render, in the file that declares the parent. */
+    line: number;
+}
 export interface ScannedComponent {
     /** Composable function name (Android) or View struct name (iOS) */
     name: string;
@@ -32,12 +49,78 @@ export interface ScannedComponent {
     line: number;
     /** Previews matched to this component (same file + name-prefix heuristic) */
     previews: ScannedPreview[];
+    /** Stored properties (iOS) or composable parameters (Android). What the
+     * component's states are derived from. */
+    properties?: ComponentProperty[];
+    /** Types read via `@Environment(X.self)` (iOS). An unsatisfied one traps at
+     * render, so a preview that omits it is broken rather than incomplete. */
+    environmentTypes?: string[];
+    /** Other discovered components this one renders in its body (iOS). What makes
+     * it possible to say who else is affected when a component changes. */
+    uses?: string[];
+    /**
+     * The subset of `uses` this component renders only inside an `if`, `switch`
+     * or `guard`. Its own preview may never reach these.
+     */
+    conditionalUses?: ConditionalUse[];
+    /** Previews this component should have and doesn't. See src/scan/gaps.ts. */
+    gaps?: CoverageGap[];
 }
 export interface CoverageReport {
     platform: 'android' | 'ios';
     components: ScannedComponent[];
     /** Previews that could not be matched to any discovered component */
     orphanPreviews: ScannedPreview[];
+    /** Locales the project ships beyond its development language. Empty when the
+     * project is not localized, which keeps the localization gap silent there. */
+    extraLocales: string[];
+    /** Present when the report was narrowed to a subset of the project's files.
+     * The scan still walked everything; only this report is filtered. */
+    scope?: {
+        paths: string[];
+        /** Components the scan found, before the filter. */
+        componentsScanned: number;
+        /**
+         * Previews outside the scope that put a component inside it on screen,
+         * directly or through the views they render. Editing a row changes what
+         * these show, and the filter would otherwise hide them. A fact to act on,
+         * not a defect.
+         */
+        previewsOfWhatChanged?: {
+            name: string;
+            file: string;
+            line: number;
+            /** In-scope components this preview reaches. Its own text may name none of them. */
+            renders: string[];
+        }[];
+        /**
+         * Views outside the scope that render a component inside it directly and
+         * have no preview of their own, so nothing shows the change in that
+         * context. Whether that context is worth covering is a judgment about the
+         * product, which is why this is a question for the designer rather than a
+         * gap — and why it stops at one hop where `previewsOfWhatChanged` does not.
+         */
+        uncoveredUsesOfWhatChanged?: {
+            component: string;
+            file: string;
+            /** The guarded render when `reason` is `conditional`, so the line points at
+             * the branch in question; the component's declaration otherwise. */
+            line: number;
+            /** In-scope components it renders. */
+            uses: string[];
+            /** Why nothing shows the change here. */
+            reason: 'no-preview' | 'conditional';
+            /** `conditional` only: the condition a preview would have to satisfy. */
+            guard?: string;
+            /** `conditional` only: the previews that exist and do not enter the branch.
+             * Naming them is what makes this answerable — the reader opens one. */
+            previews?: {
+                name: string;
+                file: string;
+                line: number;
+            }[];
+        }[];
+    };
     /** Totals for a quick summary */
     stats: {
         components: number;
@@ -45,6 +128,9 @@ export interface CoverageReport {
         withDarkPreview: number;
         totalPreviews: number;
         hintCount: number;
+        gapCount: number;
+        /** Components with at least one warning-severity gap. */
+        componentsWithGaps: number;
         /** Components whose only preview is themselves (the @Preview-on-the-composable
          * pattern for screen-level composables with default parameters). */
         selfPreviewed: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stag-build/phonebook",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Storybook-style static gallery generated from Compose @Preview / SwiftUI #Preview screenshots",
   "license": "MIT",
   "mcpName": "io.github.stag-build/phonebook",