@haystackeditor/cli 0.24.0 → 0.25.0

package/dist/telemetry/next.js

@@ -35,7 +35,7 @@ import { existsSync, readdirSync, readFileSync, realpathSync, rmSync } from 'nod
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { authenticateTelemetryRuntime, BUNDLED_SOURCE_EXTENSIONS, writeBundledTelemetryRuntime, } from '../commands/telemetry.js';
+import { authenticateTelemetryRuntime, BUNDLED_SOURCE_EXTENSIONS, settingsSummary, writeBundledTelemetryRuntime, writeInertTelemetryRuntime, } from '../commands/telemetry.js';
 const PRODUCTION_BUILD_PHASE = 'phase-production-build';
 const SESSION_ENVIRONMENT = '__HAYSTACK_TELEMETRY_NEXT_SESSION';
 // Must equal the directory names in ./next-loader.cts.
@@ -52,30 +52,88 @@ const LOADER_PATH = fileURLToPath(new URL('./next-loader.cjs', import.meta.url))
 function plainObject(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
-function gitOutput(cwd, args) {
+/** Site paths are repository-relative so they match the crawl's blast radius (`apps/web/src/...` in a monorepo). A build
+ * without git (a Docker build whose context has no .git) still instruments: paths are relative to the Next project and
+ * every source module the server compiles counts, which the manifest's source_identity says. */
+function sourceIdentity(projectDirectory) {
     try {
-        return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 256 * 1024 * 1024 });
+        const top = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: projectDirectory, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return { sourceRoot: realpathSync(top), tracked: true, identity: { git: true, lost: null } };
     }
-    catch (error) {
-        throw new Error(`Haystack telemetry needs the app's git checkout to name source files (git ${args.join(' ')} failed in ${cwd}): ` +
-            `${error instanceof Error ? error.message : String(error)}`);
+    catch {
+        return {
+            sourceRoot: projectDirectory,
+            tracked: false,
+            identity: {
+                git: false,
+                lost: 'no git checkout: site paths are relative to the Next project, not the repository (in a monorepo they do not ' +
+                    "join the change's paths), and untracked source files the server compiles are instrumented too",
+            },
+        };
+    }
+}
+/** Rule 13(b): telemetry never fails the customer's build. Anything that stops it is said once, and the build goes on
+ * without it; the build output still gets an inert preload and a report saying why. */
+function notInstrumented(reason) {
+    console.log(`Haystack telemetry: not added to this build: ${reason}`);
+}
+/** The config with only the step that leaves the inert preload and the report (so a start command that preloads it works). */
+function withInertRuntime(config, reason) {
+    notInstrumented(reason);
+    const compiler = plainObject(config.compiler);
+    const originalAfterCompile = typeof compiler.runAfterProductionCompile === 'function'
+        ? compiler.runAfterProductionCompile
+        : null;
+    return {
+        ...config,
+        compiler: {
+            ...compiler,
+            async runAfterProductionCompile(context) {
+                if (originalAfterCompile)
+                    await originalAfterCompile(context);
+                writeInert(resolve(context.projectDir, context.distDir), reason);
+            },
+        },
+    };
+}
+function writeInert(distDirectory, reason, unparsed = []) {
+    try {
+        writeInertTelemetryRuntime({ outputDirectory: distDirectory, bundler: 'next', reason, unparsed });
+    }
+    catch {
+        // A build output that cannot be written to is the build's own failure to report, not ours.
     }
 }
 export function withHaystackTelemetry(nextConfig) {
     return async (phase, context) => {
         const resolved = typeof nextConfig === 'function' ? await nextConfig(phase, context) : nextConfig;
-        return phase === PRODUCTION_BUILD_PHASE ? instrumentProductionBuild(resolved) : resolved;
+        if (phase !== PRODUCTION_BUILD_PHASE)
+            return resolved;
+        try {
+            return instrumentProductionBuild(resolved);
+        }
+        catch (error) {
+            try {
+                return withInertRuntime(resolved, error instanceof Error ? error.message : String(error));
+            }
+            catch {
+                return resolved;
+            }
+        }
     };
 }
 function instrumentProductionBuild(config) {
     if (plainObject(config.experimental).turbopackFileSystemCacheForBuild) {
         // A persisted Turbopack result skips the loader, so that module's sites
         // would never reach the manifest and its probes would count nothing.
-        throw new Error('Haystack telemetry cannot instrument a build that reuses cached Turbopack modules; turn off experimental.turbopackFileSystemCacheForBuild');
+        return withInertRuntime(config, 'it cannot instrument a build that reuses cached Turbopack modules; turn off experimental.turbopackFileSystemCacheForBuild to add it');
     }
-    // Site paths are repository-relative so they match the crawl's blast radius
-    // (`apps/web/src/...` in a monorepo), not relative to the Next project.
-    const sourceRoot = realpathSync(gitOutput(process.cwd(), ['rev-parse', '--show-toplevel']).trim());
+    const projectDirectory = realpathSync(process.cwd());
+    const { sourceRoot, tracked, identity } = sourceIdentity(projectDirectory);
+    if (!identity.git)
+        console.log(`Haystack telemetry: ${identity.lost}.`);
     // Evaluating this config has no side effects beyond naming the session:
     // `next build` re-evaluates it in every worker it spawns (page-data and
     // static-generation workers too), and loaders create what they write.
@@ -87,6 +145,9 @@ function instrumentProductionBuild(config) {
         .update(`next\0${sourceRoot}`).digest('hex').slice(0, 24)}`;
     const loaderOptions = {
         sourceRoot,
+        tracked,
+        sourceIdentity: identity,
+        projectDirectory,
         sessionDirectory,
         controlChannel,
         runtimeIntegrity: authenticateTelemetryRuntime(controlChannel).integrity,
@@ -94,7 +155,9 @@ function instrumentProductionBuild(config) {
     const loader = { loader: LOADER_PATH, options: loaderOptions };
     // Turbopack (Next 16's default bundler): server-side ("node") modules outside
     // node_modules ("foreign"). Edge and browser contexts are left alone: the
-    // runtime is Node-only.
+    // runtime is Node-only. The loader also leaves "use client" modules (their
+    // server copy is the SSR render of browser code), modules declaring
+    // `export const runtime = 'edge'`, and middleware alone.
     const turbopack = plainObject(config.turbopack);
     const rules = { ...plainObject(turbopack.rules) };
     for (const extension of BUNDLED_SOURCE_EXTENSIONS) {
@@ -133,9 +196,19 @@ function instrumentProductionBuild(config) {
         compiler: {
             ...compiler,
             async runAfterProductionCompile(context) {
+                // The application's own hook keeps its own failures.
                 if (originalAfterCompile)
                     await originalAfterCompile(context);
-                writeNextTelemetryRuntime(loaderOptions, resolve(context.projectDir, context.distDir));
+                const distDirectory = resolve(context.projectDir, context.distDir);
+                try {
+                    writeNextTelemetryRuntime(loaderOptions, distDirectory);
+                }
+                catch (error) {
+                    // Instrumented modules without an installed runtime pass every value through.
+                    const reason = error instanceof Error ? error.message : String(error);
+                    notInstrumented(reason);
+                    writeInert(distDirectory, reason);
+                }
             },
         },
     };
@@ -144,13 +217,18 @@ function writeNextTelemetryRuntime(options, distDirectory) {
     const modules = readRecords(join(options.sessionDirectory, MODULES_DIRECTORY));
     const unparsed = readRecords(join(options.sessionDirectory, UNPARSED_DIRECTORY));
     if (modules.length === 0) {
-        throw new Error(`Haystack telemetry: the bundler compiled no instrumentable tracked server module through its loader${unparsed.length > 0 ? ` (${unparsed.length} could not be parsed)` : ''}; nothing was instrumented`);
+        rmSync(options.sessionDirectory, { recursive: true, force: true });
+        const reason = `the bundler compiled no instrumentable${options.tracked ? ' tracked' : ''} server module through its loader${unparsed.length > 0 ? ` (${unparsed.length} could not be parsed or transformed)` : ''}`;
+        notInstrumented(reason);
+        writeInert(distDirectory, reason, unparsed);
+        return;
     }
     const { registerPath, manifest } = writeBundledTelemetryRuntime({
         outputDirectory: distDirectory,
         controlChannel: options.controlChannel,
         bundler: 'next',
         sourceRoot: options.sourceRoot,
+        sourceIdentity: options.sourceIdentity,
         modules,
         unparsed,
     });
@@ -158,9 +236,11 @@ function writeNextTelemetryRuntime(options, distDirectory) {
     // `next build` spawns next resolve the same (now empty) session.
     rmSync(options.sessionDirectory, { recursive: true, force: true });
     console.log(`Haystack telemetry: instrumented ${modules.length} server module(s), ${manifest.sites.length} site(s); build ${manifest.build_id}.`);
+    for (const line of settingsSummary(manifest.settings, modules.filter(module => module.typed).length, modules.length))
+        console.log(line);
     if (manifest.skipped_unparsed_files.length > 0) {
         // Named, never silent: these modules run but count nothing.
-        console.log(`Haystack telemetry: skipped ${manifest.skipped_unparsed_files.length} server module(s) Babel could not parse (shipped uninstrumented; listed in instrumentation.json skipped_unparsed_files):`);
+        console.log(`Haystack telemetry: shipped ${manifest.skipped_unparsed_files.length} server module(s) uninstrumented (Babel could not parse or transform them; listed in instrumentation.json skipped_unparsed_files):`);
         for (const file of manifest.skipped_unparsed_files)
             console.log(`  ${file.source_path}: ${file.reason}`);
     }

package/dist/telemetry/typed-source.d.ts

@@ -0,0 +1,47 @@
+/**
+ * CAPTURE-V1 rule 9(b) and 9(c): what a site's TypeScript declares, read from the ORIGINAL typed source before any
+ * compiler erases it. A parameter or binding annotated with a union of literals, a boolean, an enum, an `as const` array
+ * or object (through `(typeof X)[number]`, `typeof X[keyof typeof X]` or `keyof typeof X`) has a LITERAL DOMAIN: a
+ * settings candidate. An object type (inline, interface, alias, intersection, Partial/Required/Readonly/Pick/Omit) has
+ * DECLARED FIELDS: the names whose presence the runtime records.
+ *
+ * Types resolve within the file and through one hop of relative imports (`import type { Mode } from './types'`); a
+ * name that resolves to nothing known, a generic, a computed enum member or a template type has no domain and no
+ * fields, which leaves the site shape-only. Resolution is by declared identifier, never by text similarity.
+ */
+type Node = any;
+export type SettingLiteral = string | number | boolean;
+/** A file's type declarations by name, and where its imported names come from. */
+export interface TypeIndex {
+    aliases: Map<string, Node>;
+    interfaces: Map<string, Node[]>;
+    enums: Map<string, Node>;
+    /** `const X = [...] as const` and `const X = {...} as const`: the literal array or object. */
+    constants: Map<string, Node>;
+    imports: Map<string, {
+        source: string;
+        imported: string;
+    }>;
+    /** Names the file exports under another local name (`export { Local as Exported }`). */
+    exportedAs: Map<string, string>;
+}
+/** Finds an imported declaration: the other file's index, or null when the specifier is not a readable relative file. */
+export type TypeImportResolver = (specifier: string) => TypeIndex | null;
+/** Index one parsed program's top-level type declarations, `as const` literals and imports. */
+export declare function buildTypeIndex(program: Node): TypeIndex;
+interface Domain {
+    literals: SettingLiteral[];
+    typeNames: string[];
+}
+/** Rule 9(c): the literal domain a type annotation declares, with the type names it went through (for the refusal
+ * check), or null when the type is not a closed set of literals. */
+export declare function literalDomain(annotation: Node, index: TypeIndex, resolve: TypeImportResolver | null): Domain | null;
+/** Rule 9(b): the field names an annotation's object type declares, in declaration order. */
+export declare function declaredFields(annotation: Node, index: TypeIndex, resolve: TypeImportResolver | null): string[];
+/** The declared type of one member of an annotation's object type (a destructured parameter's property). */
+export declare function memberType(annotation: Node, key: string, index: TypeIndex, resolve: TypeImportResolver | null): {
+    annotation: Node;
+    index: TypeIndex;
+    resolve: TypeImportResolver | null;
+} | null;
+export {};

package/dist/telemetry/typed-source.js

@@ -0,0 +1,379 @@
+/**
+ * CAPTURE-V1 rule 9(b) and 9(c): what a site's TypeScript declares, read from the ORIGINAL typed source before any
+ * compiler erases it. A parameter or binding annotated with a union of literals, a boolean, an enum, an `as const` array
+ * or object (through `(typeof X)[number]`, `typeof X[keyof typeof X]` or `keyof typeof X`) has a LITERAL DOMAIN: a
+ * settings candidate. An object type (inline, interface, alias, intersection, Partial/Required/Readonly/Pick/Omit) has
+ * DECLARED FIELDS: the names whose presence the runtime records.
+ *
+ * Types resolve within the file and through one hop of relative imports (`import type { Mode } from './types'`); a
+ * name that resolves to nothing known, a generic, a computed enum member or a template type has no domain and no
+ * fields, which leaves the site shape-only. Resolution is by declared identifier, never by text similarity.
+ */
+const MAX_DEPTH = 8;
+const MAX_DECLARED_FIELDS = 256;
+function unwrapExport(statement) {
+    return statement?.type === 'ExportNamedDeclaration' || statement?.type === 'ExportDefaultDeclaration'
+        ? statement.declaration ?? null
+        : statement;
+}
+function constAssertion(expression) {
+    let current = expression;
+    while (current?.type === 'TSSatisfiesExpression')
+        current = current.expression;
+    if (current?.type === 'TSAsExpression' && current.typeAnnotation?.type === 'TSTypeReference' &&
+        current.typeAnnotation.typeName?.type === 'Identifier' && current.typeAnnotation.typeName.name === 'const') {
+        return current.expression;
+    }
+    return null;
+}
+/** Index one parsed program's top-level type declarations, `as const` literals and imports. */
+export function buildTypeIndex(program) {
+    const index = {
+        aliases: new Map(), interfaces: new Map(), enums: new Map(), constants: new Map(), imports: new Map(),
+        exportedAs: new Map(),
+    };
+    for (const statement of program?.body ?? []) {
+        if (statement?.type === 'ImportDeclaration' && typeof statement.source?.value === 'string') {
+            for (const specifier of statement.specifiers ?? []) {
+                if (specifier.type !== 'ImportSpecifier' || specifier.local?.type !== 'Identifier')
+                    continue;
+                const imported = specifier.imported?.type === 'Identifier' ? specifier.imported.name : specifier.imported?.value;
+                if (typeof imported === 'string') {
+                    index.imports.set(specifier.local.name, { source: statement.source.value, imported });
+                }
+            }
+            continue;
+        }
+        if (statement?.type === 'ExportNamedDeclaration' && !statement.declaration && !statement.source) {
+            for (const specifier of statement.specifiers ?? []) {
+                const exported = specifier.exported?.type === 'Identifier' ? specifier.exported.name : specifier.exported?.value;
+                if (specifier.local?.type === 'Identifier' && typeof exported === 'string') {
+                    index.exportedAs.set(exported, specifier.local.name);
+                }
+            }
+            continue;
+        }
+        const declaration = unwrapExport(statement);
+        if (!declaration)
+            continue;
+        if (declaration.type === 'TSTypeAliasDeclaration' && declaration.id?.name) {
+            index.aliases.set(declaration.id.name, declaration.typeAnnotation);
+        }
+        else if (declaration.type === 'TSInterfaceDeclaration' && declaration.id?.name) {
+            index.interfaces.set(declaration.id.name, [...index.interfaces.get(declaration.id.name) ?? [], declaration]);
+        }
+        else if (declaration.type === 'TSEnumDeclaration' && declaration.id?.name) {
+            index.enums.set(declaration.id.name, declaration);
+        }
+        else if (declaration.type === 'VariableDeclaration' && declaration.kind === 'const') {
+            for (const declarator of declaration.declarations ?? []) {
+                const literal = declarator.id?.type === 'Identifier' ? constAssertion(declarator.init) : null;
+                if (literal)
+                    index.constants.set(declarator.id.name, literal);
+            }
+        }
+    }
+    return index;
+}
+function lookup(name, scope, namespace) {
+    const { index } = scope;
+    if (namespace === 'type') {
+        if (index.aliases.has(name))
+            return { kind: 'alias', node: index.aliases.get(name), scope };
+        if (index.interfaces.has(name))
+            return { kind: 'interface', nodes: index.interfaces.get(name), scope };
+    }
+    if (index.enums.has(name))
+        return { kind: 'enum', node: index.enums.get(name), scope };
+    if (namespace === 'value' && index.constants.has(name))
+        return { kind: 'constant', node: index.constants.get(name), scope };
+    const imported = index.imports.get(name);
+    // One hop: an imported file's own imports are not followed.
+    if (imported && scope.resolve && scope.depth === 0) {
+        const other = scope.resolve(imported.source);
+        if (!other)
+            return null;
+        const local = other.exportedAs.get(imported.imported) ?? imported.imported;
+        return lookup(local, { index: other, resolve: null, depth: 1 }, namespace);
+    }
+    return null;
+}
+function literalValue(node) {
+    if (node?.type === 'StringLiteral')
+        return node.value;
+    if (node?.type === 'NumericLiteral')
+        return node.value;
+    if (node?.type === 'BooleanLiteral')
+        return node.value;
+    if (node?.type === 'UnaryExpression' && node.operator === '-' && node.argument?.type === 'NumericLiteral') {
+        return -node.argument.value;
+    }
+    if (node?.type === 'TemplateLiteral' && node.expressions.length === 0 && node.quasis.length === 1) {
+        return node.quasis[0].value.cooked;
+    }
+    return undefined;
+}
+function enumValues(declaration) {
+    const members = declaration.body?.members ?? declaration.members ?? [];
+    const values = [];
+    let next = 0;
+    for (const member of members) {
+        if (!member.initializer) {
+            if (next === null)
+                return null;
+            values.push(next);
+            next += 1;
+            continue;
+        }
+        const value = literalValue(member.initializer);
+        if (typeof value === 'string') {
+            values.push(value);
+            next = null;
+        }
+        else if (typeof value === 'number') {
+            values.push(value);
+            next = value + 1;
+        }
+        else {
+            // A computed member: its value is only known when the program runs.
+            return null;
+        }
+    }
+    return values;
+}
+function enumMember(declaration, memberName) {
+    const values = enumValues(declaration);
+    if (!values)
+        return null;
+    const members = declaration.body?.members ?? declaration.members ?? [];
+    const position = members.findIndex((member) => (member.id?.type === 'Identifier' ? member.id.name : member.id?.value) === memberName);
+    return position < 0 ? null : [values[position]];
+}
+function constantLiterals(node, part) {
+    const values = [];
+    if (part === 'elements') {
+        if (node?.type !== 'ArrayExpression')
+            return null;
+        for (const element of node.elements) {
+            const value = literalValue(element);
+            if (value === undefined)
+                return null;
+            values.push(value);
+        }
+        return values;
+    }
+    if (node?.type !== 'ObjectExpression')
+        return null;
+    for (const property of node.properties) {
+        if (property.type !== 'ObjectProperty' || property.computed)
+            return null;
+        if (part === 'keys') {
+            const key = property.key?.type === 'Identifier' ? property.key.name : literalValue(property.key);
+            if (key === undefined || typeof key === 'boolean')
+                return null;
+            values.push(String(key));
+        }
+        else {
+            const value = literalValue(property.value);
+            if (value === undefined)
+                return null;
+            values.push(value);
+        }
+    }
+    return values;
+}
+function queryName(node) {
+    return node?.type === 'TSTypeQuery' && node.exprName?.type === 'Identifier' ? node.exprName.name : null;
+}
+function referenceName(node) {
+    const typeName = node?.typeName;
+    if (typeName?.type === 'Identifier')
+        return { name: typeName.name, member: null };
+    if (typeName?.type === 'TSQualifiedName' && typeName.left?.type === 'Identifier' && typeName.right?.type === 'Identifier') {
+        return { name: typeName.left.name, member: typeName.right.name };
+    }
+    return null;
+}
+function hasTypeArguments(node) {
+    return Boolean((node?.typeArguments ?? node?.typeParameters)?.params?.length);
+}
+function domainOf(node, scope, depth) {
+    if (!node || depth > MAX_DEPTH)
+        return null;
+    switch (node.type) {
+        case 'TSTypeAnnotation':
+        case 'TSParenthesizedType':
+            return domainOf(node.typeAnnotation, scope, depth + 1);
+        case 'TSBooleanKeyword':
+            return { literals: [true, false], typeNames: [] };
+        case 'TSLiteralType': {
+            const value = literalValue(node.literal);
+            return value === undefined ? null : { literals: [value], typeNames: [] };
+        }
+        case 'TSUndefinedKeyword':
+        case 'TSNullKeyword':
+        case 'TSVoidKeyword':
+            // Nullish members are the vocabulary's own categories, never literals.
+            return { literals: [], typeNames: [] };
+        case 'TSUnionType': {
+            const literals = [];
+            const typeNames = [];
+            for (const member of node.types) {
+                const domain = domainOf(member, scope, depth + 1);
+                if (!domain)
+                    return null;
+                for (const literal of domain.literals)
+                    if (!literals.some(known => Object.is(known, literal)))
+                        literals.push(literal);
+                typeNames.push(...domain.typeNames);
+            }
+            return { literals, typeNames };
+        }
+        case 'TSTypeOperator': {
+            if (node.operator === 'readonly')
+                return domainOf(node.typeAnnotation, scope, depth + 1);
+            const name = node.operator === 'keyof' ? queryName(node.typeAnnotation) : null;
+            const declaration = name ? lookup(name, scope, 'value') : null;
+            if (declaration?.kind !== 'constant')
+                return null;
+            const literals = constantLiterals(declaration.node, 'keys');
+            return literals ? { literals, typeNames: [name] } : null;
+        }
+        case 'TSIndexedAccessType': {
+            const name = queryName(node.objectType);
+            const declaration = name ? lookup(name, scope, 'value') : null;
+            if (declaration?.kind !== 'constant')
+                return null;
+            // (typeof X)[number] over an `as const` array; typeof X[keyof typeof X] over an `as const` object.
+            if (node.indexType?.type === 'TSNumberKeyword') {
+                const literals = constantLiterals(declaration.node, 'elements');
+                return literals ? { literals, typeNames: [name] } : null;
+            }
+            if (node.indexType?.type === 'TSTypeOperator' && node.indexType.operator === 'keyof' &&
+                queryName(node.indexType.typeAnnotation) === name) {
+                const literals = constantLiterals(declaration.node, 'values');
+                return literals ? { literals, typeNames: [name] } : null;
+            }
+            return null;
+        }
+        case 'TSTypeReference': {
+            const reference = referenceName(node);
+            if (!reference || hasTypeArguments(node))
+                return null;
+            const declaration = lookup(reference.name, scope, 'type');
+            if (!declaration)
+                return null;
+            if (declaration.kind === 'enum') {
+                const literals = reference.member ? enumMember(declaration.node, reference.member) : enumValues(declaration.node);
+                return literals ? { literals, typeNames: [reference.name] } : null;
+            }
+            if (reference.member || declaration.kind !== 'alias')
+                return null;
+            const domain = domainOf(declaration.node, declaration.scope, depth + 1);
+            return domain ? { literals: domain.literals, typeNames: [reference.name, ...domain.typeNames] } : null;
+        }
+        default:
+            return null;
+    }
+}
+/** Rule 9(c): the literal domain a type annotation declares, with the type names it went through (for the refusal
+ * check), or null when the type is not a closed set of literals. */
+export function literalDomain(annotation, index, resolve) {
+    const domain = domainOf(annotation, { index, resolve, depth: 0 }, 0);
+    return domain && domain.literals.length > 0 ? domain : null;
+}
+function memberKey(member) {
+    if (member?.type !== 'TSPropertySignature' || member.computed)
+        return null;
+    if (member.key?.type === 'Identifier')
+        return member.key.name;
+    if (member.key?.type === 'StringLiteral')
+        return member.key.value;
+    return null;
+}
+function keyLiterals(node, scope) {
+    const domain = domainOf(node, scope, 0);
+    return domain && domain.literals.every(literal => typeof literal === 'string') ? domain.literals : null;
+}
+/** Each declared member of an object type, by name, with the scope its type resolves in. */
+function membersOf(node, scope, depth, out) {
+    if (!node || depth > MAX_DEPTH)
+        return false;
+    switch (node.type) {
+        case 'TSTypeAnnotation':
+        case 'TSParenthesizedType':
+            return membersOf(node.typeAnnotation, scope, depth + 1, out);
+        case 'TSTypeLiteral':
+            for (const member of node.members) {
+                const key = memberKey(member);
+                if (key !== null && !out.has(key))
+                    out.set(key, { type: member.typeAnnotation, scope });
+            }
+            return true;
+        case 'TSIntersectionType':
+        case 'TSUnionType': {
+            let any = false;
+            for (const member of node.types)
+                any = membersOf(member, scope, depth + 1, out) || any;
+            return any;
+        }
+        case 'TSTypeReference': {
+            const reference = referenceName(node);
+            if (!reference || reference.member)
+                return false;
+            const typeArguments = (node.typeArguments ?? node.typeParameters)?.params ?? [];
+            if (['Partial', 'Required', 'Readonly', 'NonNullable'].includes(reference.name) && typeArguments.length === 1) {
+                return membersOf(typeArguments[0], scope, depth + 1, out);
+            }
+            if ((reference.name === 'Pick' || reference.name === 'Omit') && typeArguments.length === 2) {
+                const all = new Map();
+                if (!membersOf(typeArguments[0], scope, depth + 1, all))
+                    return false;
+                const keys = keyLiterals(typeArguments[1], scope);
+                if (!keys)
+                    return false;
+                for (const [key, value] of all) {
+                    if ((reference.name === 'Pick') === keys.includes(key) && !out.has(key))
+                        out.set(key, value);
+                }
+                return true;
+            }
+            if (typeArguments.length > 0)
+                return false;
+            const declaration = lookup(reference.name, scope, 'type');
+            if (declaration?.kind === 'alias')
+                return membersOf(declaration.node, declaration.scope, depth + 1, out);
+            if (declaration?.kind !== 'interface')
+                return false;
+            for (const interfaceNode of declaration.nodes) {
+                for (const member of interfaceNode.body?.body ?? []) {
+                    const key = memberKey(member);
+                    if (key !== null && !out.has(key))
+                        out.set(key, { type: member.typeAnnotation, scope: declaration.scope });
+                }
+                for (const heritage of interfaceNode.extends ?? []) {
+                    const expression = heritage.expression;
+                    if (expression?.type === 'Identifier') {
+                        membersOf({ type: 'TSTypeReference', typeName: expression, typeArguments: heritage.typeArguments ?? heritage.typeParameters }, declaration.scope, depth + 1, out);
+                    }
+                }
+            }
+            return true;
+        }
+        default:
+            return false;
+    }
+}
+/** Rule 9(b): the field names an annotation's object type declares, in declaration order. */
+export function declaredFields(annotation, index, resolve) {
+    const members = new Map();
+    membersOf(annotation, { index, resolve, depth: 0 }, 0, members);
+    return [...members.keys()].slice(0, MAX_DECLARED_FIELDS);
+}
+/** The declared type of one member of an annotation's object type (a destructured parameter's property). */
+export function memberType(annotation, key, index, resolve) {
+    const members = new Map();
+    membersOf(annotation, { index, resolve, depth: 0 }, 0, members);
+    const member = members.get(key);
+    return member?.type ? { annotation: member.type, index: member.scope.index, resolve: member.scope.resolve } : null;
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@haystackeditor/cli",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "haystack verify: run your app with and without a change, and see what the change broke",
   "type": "module",
   "bin": {
-    "haystack": "dist/index.js"
+    "haystack": "dist/index.js",
+    "haystack-capture-step": "dist/capture-step.js"
   },
   "exports": {
     "./next": {
@@ -54,6 +55,7 @@
     "chalk": "6.0.0",
     "commander": "15.0.0",
     "fast-glob": "3.3.3",
+    "parse5-sax-parser": "8.0.0",
     "pg": "8.23.0",
     "pg-connection-string": "2.14.0",
     "ws": "8.21.3",