styleproof 3.20.0 → 4.0.0

package/dist/index.js

@@ -1,5 +1,6 @@
-export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
+export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests, trackDataResidue, urlMatcher, } from './capture.js';
 export * from './inventory.js';
+export * from './data-residue.js';
 export { captureUrlToDir, runCaptureUrl, parseCaptureUrlArgs, UsageError } from './capture-url.js';
 export { crawlAndCapture, CRAWL_DEFAULTS } from './crawl-surfaces.js';
 export { loadSetupSteps } from './capture-url.js';

package/dist/map-store.d.ts

@@ -61,7 +61,12 @@ export declare function expectedCompatibilityKey(options?: {
 }): string;
 export declare function currentGitSha(cwd?: string, env?: NodeJS.ProcessEnv): string;
 export declare function refSha(ref: string, cwd?: string): string;
-export declare function workingTreeDirty(cwd?: string): boolean;
+/**
+ * True if any tracked file is modified/added/deleted. `ignorePrefix` (a repo-relative
+ * directory) is excluded — pass the map OUTPUT dir when re-sampling AFTER a capture, so
+ * the maps the capture just wrote don't read as tree dirt and mask a real source edit.
+ */
+export declare function workingTreeDirty(cwd?: string, ignorePrefix?: string): boolean;
 export declare function remoteExists(remote?: string, cwd?: string): boolean;
 export declare function writeMapManifest(options: {
     dir: string;
@@ -72,7 +77,38 @@ export declare function writeMapManifest(options: {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
 }): MapManifest;
+/**
+ * Write a `styleproof-manifest.json` for a one-shot `styleproof-capture` output dir,
+ * so a two-directory `styleproof-diff design <build>` has the same-environment guard
+ * on both sides (v4 refuses to compare a manifest-less side). Unlike
+ * {@link writeMapManifest}, this may run OUTSIDE a git repo (a design mockup, a static
+ * export), so the git-derived fields degrade gracefully: `sha` falls back to
+ * `'uncommitted'` and `dirty` to `true` rather than throwing. The parts the guard
+ * actually consumes — `compatibilityKey`, `platform`/`arch`/`nodeMajor`,
+ * `playwrightVersion`, `browserVersion`, `baseUrl` — are recorded the same way as a
+ * spec capture. Overwrites any existing manifest in `dir`.
+ */
+export declare function writeCaptureManifest(options: {
+    dir: string;
+    screenshots: boolean;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): MapManifest;
 export declare function readMapManifest(dir: string): MapManifest | null;
+/** Which side(s) of a two-directory compare hold captured maps but NO
+ *  `styleproof-manifest.json` — a legacy committed-map bundle. Since v4 that is
+ *  unsupported: without a manifest the same-environment guard can't be enforced, so the
+ *  CLI refuses (exit 2). `null` means every side WITH maps also has a manifest (nothing to
+ *  refuse). A side with zero maps is NOT flagged — an empty/bare dir is "no baseline yet",
+ *  handled by the base/head-missing guards, not this one. Pure: presence reads only, so the
+ *  CLI layer owns the exit code and the library stays side-effect-free. */
+export declare function manifestlessSide(beforeDir: string, afterDir: string): 'before' | 'after' | 'both' | null;
+/** Fail-loud message for a manifest-less compare. Since v4 a side without a
+ *  `styleproof-manifest.json` is unsupported: the same-environment guard can't be
+ *  enforced, so captures from different browser builds or platforms would diff as
+ *  false changes. The CLI raises this and exits 2 (usage/capture error) — the
+ *  legacy "compare anyway" tolerance is gone. */
+export declare function manifestlessError(side: 'before' | 'after' | 'both'): string;
 export declare function assertCompatibleMapDirs(beforeDir: string, afterDir: string): void;
 export declare function publishMapBundle(options: {
     dir: string;

package/dist/map-store.js

@@ -153,28 +153,40 @@ export function refSha(ref, cwd = process.cwd()) {
         throw new MapStoreError(`could not resolve ${ref} to a commit`);
     return sha;
 }
-export function workingTreeDirty(cwd = process.cwd()) {
+/**
+ * True if any tracked file is modified/added/deleted. `ignorePrefix` (a repo-relative
+ * directory) is excluded — pass the map OUTPUT dir when re-sampling AFTER a capture, so
+ * the maps the capture just wrote don't read as tree dirt and mask a real source edit.
+ */
+export function workingTreeDirty(cwd = process.cwd(), ignorePrefix) {
     const r = runGit(cwd, ['status', '--porcelain']);
     const status = r.status === 0 ? r.stdout.trimEnd() : '';
     if (!status)
         return false;
+    const prefix = ignorePrefix ? `${ignorePrefix.replace(/\/+$/, '')}/` : undefined;
     return status.split(/\r?\n/).some((line) => {
         const file = line.slice(3).trim();
-        return file && !GENERATED_DIRTY_ALLOWLIST.has(file);
+        if (!file || GENERATED_DIRTY_ALLOWLIST.has(file))
+            return false;
+        if (prefix && (file === prefix.slice(0, -1) || file.startsWith(prefix)))
+            return false;
+        return true;
     });
 }
 export function remoteExists(remote = DEFAULT_REMOTE, cwd = process.cwd()) {
     return runGit(cwd, ['remote', 'get-url', remote], 1 << 20).status === 0;
 }
-export function writeMapManifest(options) {
-    const cwd = options.cwd ?? process.cwd();
-    const input = compatibilityInput({ cwd, spec: options.spec, baseUrl: options.env?.BASE_URL ?? process.env.BASE_URL });
-    const browserVersion = readBrowserBuildSidecar(options.dir);
-    const manifest = {
+/** Assemble a {@link MapManifest} from the compatibility inputs and the caller-resolved
+ *  git fields. Shared by {@link writeMapManifest} (spec capture) and
+ *  {@link writeCaptureManifest} (one-shot capture) so the object shape lives in one place. */
+function buildManifest(options) {
+    const { dir, input } = options;
+    const browserVersion = readBrowserBuildSidecar(dir);
+    return {
         version: 1,
         packageVersion: input.packageVersion,
-        sha: options.sha ?? currentGitSha(cwd, options.env),
-        dirty: options.dirty ?? workingTreeDirty(cwd),
+        sha: options.sha,
+        dirty: options.dirty,
         spec: input.spec,
         specHash: input.specHash,
         ...(input.lockfile ? { lockfile: input.lockfile } : {}),
@@ -186,10 +198,49 @@ export function writeMapManifest(options) {
         nodeMajor: input.nodeMajor,
         ...(input.baseUrl ? { baseUrl: input.baseUrl } : {}),
         screenshots: options.screenshots,
-        har: hasHar(options.dir),
+        har: hasHar(dir),
         compatibilityKey: hash(JSON.stringify(input)).slice(0, 16),
         createdAt: new Date().toISOString(),
     };
+}
+export function writeMapManifest(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const input = compatibilityInput({ cwd, spec: options.spec, baseUrl: options.env?.BASE_URL ?? process.env.BASE_URL });
+    const manifest = buildManifest({
+        dir: options.dir,
+        input,
+        sha: options.sha ?? currentGitSha(cwd, options.env),
+        dirty: options.dirty ?? workingTreeDirty(cwd),
+        screenshots: options.screenshots,
+    });
+    fs.writeFileSync(path.join(options.dir, MAP_MANIFEST), JSON.stringify(manifest, null, 2));
+    return manifest;
+}
+/**
+ * Write a `styleproof-manifest.json` for a one-shot `styleproof-capture` output dir,
+ * so a two-directory `styleproof-diff design <build>` has the same-environment guard
+ * on both sides (v4 refuses to compare a manifest-less side). Unlike
+ * {@link writeMapManifest}, this may run OUTSIDE a git repo (a design mockup, a static
+ * export), so the git-derived fields degrade gracefully: `sha` falls back to
+ * `'uncommitted'` and `dirty` to `true` rather than throwing. The parts the guard
+ * actually consumes — `compatibilityKey`, `platform`/`arch`/`nodeMajor`,
+ * `playwrightVersion`, `browserVersion`, `baseUrl` — are recorded the same way as a
+ * spec capture. Overwrites any existing manifest in `dir`.
+ */
+export function writeCaptureManifest(options) {
+    const cwd = options.cwd ?? process.cwd();
+    // A one-shot capture has no spec file; key comparability off the capture inputs only.
+    const input = compatibilityInput({ cwd, spec: MAP_MANIFEST, baseUrl: options.env?.BASE_URL ?? process.env.BASE_URL });
+    // Degrade the git fields gracefully outside a repo (a design mockup): no HEAD → uncommitted/dirty.
+    const sha = gitOutput(cwd, ['rev-parse', 'HEAD']) || 'uncommitted';
+    const manifest = buildManifest({
+        dir: options.dir,
+        input,
+        sha,
+        dirty: sha === 'uncommitted' ? true : workingTreeDirty(cwd),
+        screenshots: options.screenshots,
+    });
+    fs.mkdirSync(options.dir, { recursive: true });
     fs.writeFileSync(path.join(options.dir, MAP_MANIFEST), JSON.stringify(manifest, null, 2));
     return manifest;
 }
@@ -201,6 +252,48 @@ export function readMapManifest(dir) {
         return null;
     }
 }
+/** True if `dir` holds at least one captured surface map (`<key>@<width>.json[.gz]`),
+ *  ignoring metadata sidecars. Distinguishes a real capture that merely lacks a manifest
+ *  (a legacy committed-map bundle — v4 refuses it) from an empty/bare dir (no baseline
+ *  yet — the missing-map guards own that). */
+function dirHasMaps(dir) {
+    try {
+        return fs.readdirSync(dir).some(isMapFile);
+    }
+    catch {
+        return false;
+    }
+}
+/** Which side(s) of a two-directory compare hold captured maps but NO
+ *  `styleproof-manifest.json` — a legacy committed-map bundle. Since v4 that is
+ *  unsupported: without a manifest the same-environment guard can't be enforced, so the
+ *  CLI refuses (exit 2). `null` means every side WITH maps also has a manifest (nothing to
+ *  refuse). A side with zero maps is NOT flagged — an empty/bare dir is "no baseline yet",
+ *  handled by the base/head-missing guards, not this one. Pure: presence reads only, so the
+ *  CLI layer owns the exit code and the library stays side-effect-free. */
+export function manifestlessSide(beforeDir, afterDir) {
+    const before = dirHasMaps(beforeDir) && readMapManifest(beforeDir) == null;
+    const after = dirHasMaps(afterDir) && readMapManifest(afterDir) == null;
+    if (before && after)
+        return 'both';
+    if (before)
+        return 'before';
+    if (after)
+        return 'after';
+    return null;
+}
+/** Fail-loud message for a manifest-less compare. Since v4 a side without a
+ *  `styleproof-manifest.json` is unsupported: the same-environment guard can't be
+ *  enforced, so captures from different browser builds or platforms would diff as
+ *  false changes. The CLI raises this and exits 2 (usage/capture error) — the
+ *  legacy "compare anyway" tolerance is gone. */
+export function manifestlessError(side) {
+    const carry = side === 'both' ? 'before and after carry' : `${side} carries`;
+    return (`styleproof: ${carry} no ${MAP_MANIFEST} — environment compatibility can't be verified, so ` +
+        'captures from different browser builds or platforms would diff as false changes. ' +
+        'Re-capture with current StyleProof (styleproof-map, or styleproof-capture for a one-shot ' +
+        'diff); maps without a manifest are unsupported since v4.');
+}
 export function assertCompatibleMapDirs(beforeDir, afterDir) {
     const before = readMapManifest(beforeDir);
     const after = readMapManifest(afterDir);

package/dist/report.d.ts

@@ -1,5 +1,5 @@
-import { type PropChange } from './diff.js';
 export { describeChange, colorName, tokenIndex, toHex } from './describe.js';
+export { summarizeProps, prettyLabel } from './change-groups.js';
 /**
  * Visual diff report: for every surface with findings, crop the before/after
  * full-page screenshots around the changed elements and write a markdown
@@ -77,8 +77,5 @@ export type ReportResult = {
     reportMdPath: string;
     reportJsonPath: string;
 };
-export declare function summarizeProps(props: PropChange[]): PropChange[];
-/** `div.who-grid`, `a.nav-cta`, `h3` — the semantic marker class, else the tag. */
-export declare function prettyLabel(p: string, cls: string): string;
 export declare function excerptPair(before: string, after: string): [string, string];
 export declare function generateStyleMapReport(opts: ReportOptions): ReportResult;