carrick 0.3.81 → 0.3.83

package/sidecar/dist/src/capture/check-deep.d.ts

@@ -15,6 +15,7 @@
  * changes because of it, so a scan's verdicts are identical with and without
  * it — what changes is whether a reader is told the verdict is a fact.
  */
+import ts from 'typescript';
 import type { TypeProvenance } from './api.js';
 import type { ProbePlan } from './check-probe.js';
 /** Deep findings for one pair, per probe side. */
@@ -22,11 +23,22 @@ export interface PairDeepFindings {
     sent: TypeProvenance[];
     expected: TypeProvenance[];
 }
+/** The one compiler program over the assembled probes, shared by every
+ * post-judge walk (fact-ness, and the field-level report the mismatch text
+ * names). Built once: two `createProgram` calls over the same file set would
+ * double the check phase's most expensive step and could not disagree usefully
+ * anyway. `undefined` when it cannot be built at all. */
+export interface ProbeProgram {
+    program: ts.Program;
+    checker: ts.TypeChecker;
+    probesDir: string;
+}
+export declare function openProbeProgram(probesDir: string, plans: ProbePlan[]): ProbeProgram | undefined;
 /**
  * Walk both sides of every probe in the assembled workspace.
  *
- * Returns an empty map when the program cannot be built — absence of findings
- * must never be read as "clean", so the caller treats a missing entry as
- * unresolved rather than resolved.
+ * Returns an empty map when the program could not be built — absence of
+ * findings must never be read as "clean", so the caller treats a missing entry
+ * as unresolved rather than resolved.
  */
-export declare function probeDeepFindings(probesDir: string, plans: ProbePlan[]): Map<string, PairDeepFindings>;
+export declare function probeDeepFindings(opened: ProbeProgram | undefined, plans: ProbePlan[]): Map<string, PairDeepFindings>;

package/sidecar/dist/src/capture/check-deep.js

@@ -19,37 +19,41 @@ import ts from 'typescript';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { findDisqualifyingTopTypes, provenanceOf } from './deep-walk.js';
-/**
- * Walk both sides of every probe in the assembled workspace.
- *
- * Returns an empty map when the program cannot be built — absence of findings
- * must never be read as "clean", so the caller treats a missing entry as
- * unresolved rather than resolved.
- */
-export function probeDeepFindings(probesDir, plans) {
-    const results = new Map();
+export function openProbeProgram(probesDir, plans) {
     if (plans.length === 0)
-        return results;
+        return undefined;
     const configPath = path.join(probesDir, 'tsconfig.json');
     if (!fs.existsSync(configPath))
-        return results;
-    let program;
+        return undefined;
     try {
         const raw = ts.readConfigFile(configPath, (f) => fs.readFileSync(f, 'utf8'));
         if (raw.error)
-            return results;
+            return undefined;
         const parsed = ts.parseJsonConfigFileContent(raw.config, ts.sys, probesDir);
         const fileNames = plans
             .map((plan) => path.join(probesDir, 'probes', plan.fileName))
             .filter((f) => fs.existsSync(f));
         if (fileNames.length === 0)
-            return results;
-        program = ts.createProgram(fileNames, { ...parsed.options, noEmit: true });
+            return undefined;
+        const program = ts.createProgram(fileNames, { ...parsed.options, noEmit: true });
+        return { program, checker: program.getTypeChecker(), probesDir };
     }
     catch {
-        return results;
+        return undefined;
     }
-    const checker = program.getTypeChecker();
+}
+/**
+ * Walk both sides of every probe in the assembled workspace.
+ *
+ * Returns an empty map when the program could not be built — absence of
+ * findings must never be read as "clean", so the caller treats a missing entry
+ * as unresolved rather than resolved.
+ */
+export function probeDeepFindings(opened, plans) {
+    const results = new Map();
+    if (!opened)
+        return results;
+    const { program, checker, probesDir } = opened;
     for (const plan of plans) {
         const file = program.getSourceFile(path.join(probesDir, 'probes', plan.fileName));
         if (!file)

package/sidecar/dist/src/capture/check-fields.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Field-level report for a pair the judge called incompatible
+ * (carrick-tools/carrick-cloud#1118).
+ *
+ * `tsc` decides. Its elaboration names ONE field and then elides the rest
+ * ("Type 'A' is not assignable to type 'B'. Property 'x' is missing"), which is
+ * not enough for a reader deciding what to change: a create endpoint that
+ * requires `username` while the client sends `userName` reads as one missing
+ * property with no hint that the sent object carries a near-neighbour.
+ *
+ * This walk enumerates the differing fields of the SAME two types the judge
+ * compared, in the SAME program, using the compiler's own assignability
+ * relation. It is not a second judge:
+ *   - it runs only after the bucket is decided and never changes one;
+ *   - it never contradicts: a difference is only named when the checker itself
+ *     says the two member types do not assign, and when it finds nothing it
+ *     adds nothing and the raw tsc text stands alone;
+ *   - it refuses the shapes where a member list is not an account of the type
+ *     (a union root, a receiver with an index signature), rather than guessing
+ *     about them.
+ *
+ * It reports one thing the judge structurally cannot: an optionality gap in the
+ * direction that still assigns (the sending side always provides a field the
+ * receiving side declares optional). That is a real drift between two sources
+ * — the receiver carries a branch that never runs — and no assignment error can
+ * exist for it. It is stated as an observation beside the verdict, never as the
+ * verdict.
+ *
+ * Seam: node builtins + `typescript` + this bundle only.
+ */
+import type { ProbePlan, Side } from './check-probe.js';
+import type { ProbeProgram } from './check-deep.js';
+/** What kind of difference one field path carries. */
+export type FieldDifferenceNature = 
+/** The receiving side declares it; the sending side has no such member. */
+'missing_in_sent'
+/** The sending side provides it; the receiving side declares no such member. */
+ | 'extra_in_sent'
+/** Optional where it is sent, required where it is read. */
+ | 'optional_in_sent'
+/** Always sent, optional where it is read (no assignment error can exist). */
+ | 'optional_in_expected'
+/** Both declare it and the member types do not assign. */
+ | 'type_differs';
+export interface FieldDifference {
+    /** Dotted member path from the compared root (`''` is the root itself). */
+    path: string;
+    nature: FieldDifferenceNature;
+    /** Printed member type on the sending side, for `type_differs`. */
+    sentText?: string;
+    /** Printed member type on the receiving side, for `type_differs`. */
+    expectedText?: string;
+}
+export interface PairFieldReport {
+    /** Named differences, capped and ordered deterministically. */
+    differences: FieldDifference[];
+    /** How many further differences were found beyond the cap. */
+    truncated: number;
+    /**
+     * Whether the sent type's JSON wire form differs from its declared form, so
+     * the comparison the reader is being shown is against the serialised shape
+     * (a `Date` compared as the string it serialises to).
+     */
+    wireApplied: boolean;
+}
+/**
+ * Cap on named fields. A mismatch with more differing members than this is
+ * better described as two unrelated shapes than as a list, and the text says
+ * how many more there are rather than pretending the list is complete.
+ */
+export declare const MAX_NAMED_FIELDS = 8;
+/**
+ * Field reports for every plan whose probe the program could read, keyed by
+ * pair id. A plan with no entry has no report, which is not a claim that its
+ * types agree.
+ */
+export declare function pairFieldReports(opened: ProbeProgram | undefined, plans: ProbePlan[]): Map<string, PairFieldReport>;
+/**
+ * The sentence appended to a mismatch diagnostic. Names the two sides as
+ * producer and consumer (never the probe's internal sent/expected), so the
+ * reader knows which repo to change.
+ */
+export declare function describeFieldReport(report: PairFieldReport, sentSide: Side, expectedSide: Side): string;

package/sidecar/dist/src/capture/check-fields.js

@@ -0,0 +1,259 @@
+/**
+ * Field-level report for a pair the judge called incompatible
+ * (carrick-tools/carrick-cloud#1118).
+ *
+ * `tsc` decides. Its elaboration names ONE field and then elides the rest
+ * ("Type 'A' is not assignable to type 'B'. Property 'x' is missing"), which is
+ * not enough for a reader deciding what to change: a create endpoint that
+ * requires `username` while the client sends `userName` reads as one missing
+ * property with no hint that the sent object carries a near-neighbour.
+ *
+ * This walk enumerates the differing fields of the SAME two types the judge
+ * compared, in the SAME program, using the compiler's own assignability
+ * relation. It is not a second judge:
+ *   - it runs only after the bucket is decided and never changes one;
+ *   - it never contradicts: a difference is only named when the checker itself
+ *     says the two member types do not assign, and when it finds nothing it
+ *     adds nothing and the raw tsc text stands alone;
+ *   - it refuses the shapes where a member list is not an account of the type
+ *     (a union root, a receiver with an index signature), rather than guessing
+ *     about them.
+ *
+ * It reports one thing the judge structurally cannot: an optionality gap in the
+ * direction that still assigns (the sending side always provides a field the
+ * receiving side declares optional). That is a real drift between two sources
+ * — the receiver carries a branch that never runs — and no assignment error can
+ * exist for it. It is stated as an observation beside the verdict, never as the
+ * verdict.
+ *
+ * Seam: node builtins + `typescript` + this bundle only.
+ */
+import ts from 'typescript';
+/**
+ * Cap on named fields. A mismatch with more differing members than this is
+ * better described as two unrelated shapes than as a list, and the text says
+ * how many more there are rather than pretending the list is complete.
+ */
+export const MAX_NAMED_FIELDS = 8;
+/** Printed member types are for reading, not for re-parsing. */
+const MAX_TYPE_TEXT = 80;
+/** Depth cap on the structural descent. Deeper differences are reported at the
+ * deepest ancestor the walk reached, never dropped. */
+const MAX_FIELD_DEPTH = 4;
+function assignabilityOf(checker) {
+    const fn = checker.isTypeAssignableTo;
+    return typeof fn === 'function' ? fn.bind(checker) : undefined;
+}
+/**
+ * Field reports for every plan whose probe the program could read, keyed by
+ * pair id. A plan with no entry has no report, which is not a claim that its
+ * types agree.
+ */
+export function pairFieldReports(opened, plans) {
+    const results = new Map();
+    if (!opened)
+        return results;
+    const { program, checker, probesDir } = opened;
+    const isAssignableTo = assignabilityOf(checker);
+    if (!isAssignableTo)
+        return results;
+    for (const plan of plans) {
+        const file = program.getSourceFile(`${probesDir}/probes/${plan.fileName}`.split('\\').join('/'));
+        const source = file ??
+            program
+                .getSourceFiles()
+                .find((sf) => sf.fileName.endsWith(`/probes/${plan.fileName}`));
+        if (!source)
+            continue;
+        // Whatever the judge's decisive assignment actually sent: the GraphQL
+        // comparand where one exists, then the JSON wire form where one exists.
+        // Reading `sent` there instead would describe a type the judge did not
+        // compare, which is the one way this walk could contradict it.
+        const declared = declaredConstType(source, checker, 'sentComparand') ??
+            declaredConstType(source, checker, 'sent');
+        const expected = declaredConstType(source, checker, 'expected');
+        if (!declared || !expected)
+            continue;
+        const wire = declaredConstType(source, checker, 'sentWire');
+        const compared = wire ?? declared;
+        const report = diffReport(compared.type, expected.type, checker, isAssignableTo, expected.node);
+        report.wireApplied =
+            wire !== undefined &&
+                !(isAssignableTo(wire.type, declared.type) && isAssignableTo(declared.type, wire.type));
+        results.set(plan.pairId, report);
+    }
+    return results;
+}
+/** The type of one of the probe's declared consts, read where it is declared. */
+function declaredConstType(file, checker, name) {
+    for (const statement of file.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name)
+                continue;
+            const type = checker.getTypeAtLocation(declaration.name);
+            if (!type)
+                return undefined;
+            return { type, node: declaration.name };
+        }
+    }
+    return undefined;
+}
+function diffReport(sent, expected, checker, isAssignableTo, at) {
+    const found = [];
+    walk(sent, expected, '', 0, { checker, isAssignableTo, at, found });
+    found.sort((a, b) => a.path === b.path ? compareText(a.nature, b.nature) : compareText(a.path, b.path));
+    return {
+        differences: found.slice(0, MAX_NAMED_FIELDS),
+        truncated: Math.max(0, found.length - MAX_NAMED_FIELDS),
+        wireApplied: false,
+    };
+}
+function compareText(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * A shape whose members can be compared one by one without diverging from the
+ * whole-type relation.
+ *
+ * The object flag is the first and widest of these: a union or an intersection
+ * does not carry it, and neither does a primitive, so a root the judge compared
+ * as a whole is never taken apart into members one of its constituents happens
+ * to share.
+ *
+ * An index signature is excluded because it makes the member list an incomplete
+ * account of the type: a field the sender provides that the receiver's index
+ * signature accepts is not a field the receiver "declares no such field" for,
+ * and saying so would be false. Arrays and tuples carry a numeric one, so the
+ * same clause keeps `length` and `push` out of a field list; an element
+ * difference is reported at the field that holds the array.
+ */
+function isComparableObject(type, checker) {
+    if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never)) {
+        return false;
+    }
+    if ((type.flags & ts.TypeFlags.Object) === 0)
+        return false;
+    if (checker.getIndexInfosOfType(type).length > 0)
+        return false;
+    return true;
+}
+function walk(sent, expected, path, depth, ctx) {
+    const { checker } = ctx;
+    if (!isComparableObject(sent, checker) || !isComparableObject(expected, checker)) {
+        return;
+    }
+    const sentProps = new Map(sent.getProperties().map((p) => [p.getName(), p]));
+    const expectedProps = new Map(expected.getProperties().map((p) => [p.getName(), p]));
+    /** Members the receiver declares and the sender has no member for, optional
+     * ones included. Only the REQUIRED ones are a difference; the rest still
+     * count here, because a receiver waiting on a member it never gets is what
+     * makes a sender-only member worth naming beside it. */
+    let absent = 0;
+    for (const [name, expectedProp] of expectedProps) {
+        const at = join(path, name);
+        const sentProp = sentProps.get(name);
+        if (!sentProp) {
+            absent += 1;
+            // An optional member the sender omits is what optional MEANS. Naming it
+            // would state that the receiver requires it, which is false, and it is
+            // not what the judge rejected the pair for.
+            if (!isOptional(expectedProp)) {
+                ctx.found.push({ path: at, nature: 'missing_in_sent' });
+            }
+            continue;
+        }
+        const sentOptional = isOptional(sentProp);
+        const expectedOptional = isOptional(expectedProp);
+        if (sentOptional && !expectedOptional) {
+            ctx.found.push({ path: at, nature: 'optional_in_sent' });
+        }
+        else if (!sentOptional && expectedOptional) {
+            // No assignment error exists for this direction, which is exactly why
+            // the judge cannot report it and this walk must.
+            ctx.found.push({ path: at, nature: 'optional_in_expected' });
+        }
+        const sentType = memberType(sentProp, ctx);
+        const expectedType = memberType(expectedProp, ctx);
+        if (ctx.isAssignableTo(sentType, expectedType))
+            continue;
+        const sentInner = checker.getNonNullableType(sentType);
+        const expectedInner = checker.getNonNullableType(expectedType);
+        if (depth + 1 < MAX_FIELD_DEPTH &&
+            isComparableObject(sentInner, checker) &&
+            isComparableObject(expectedInner, checker)) {
+            walk(sentInner, expectedInner, at, depth + 1, ctx);
+            continue;
+        }
+        ctx.found.push({
+            path: at,
+            nature: 'type_differs',
+            sentText: printType(sentType, ctx),
+            expectedText: printType(expectedType, ctx),
+        });
+    }
+    // A field the sender provides that the receiver does not declare is normal
+    // (a response carrying more than a call site reads), so it is only worth
+    // naming beside a member the receiver is waiting on and does not get: that
+    // pairing is what a renamed or relocated field looks like from the outside.
+    // On the common subset case — a call site reading fewer fields than the
+    // producer returns — nothing is absent and nothing is named.
+    if (absent === 0)
+        return;
+    for (const [name] of sentProps) {
+        if (expectedProps.has(name))
+            continue;
+        ctx.found.push({ path: join(path, name), nature: 'extra_in_sent' });
+    }
+}
+function join(path, name) {
+    return path === '' ? name : `${path}.${name}`;
+}
+function isOptional(symbol) {
+    return (symbol.flags & ts.SymbolFlags.Optional) !== 0;
+}
+function memberType(symbol, ctx) {
+    return ctx.checker.getTypeOfSymbolAtLocation(symbol, ctx.at);
+}
+function printType(type, ctx) {
+    const text = ctx.checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.InTypeAlias);
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > MAX_TYPE_TEXT ? `${flat.slice(0, MAX_TYPE_TEXT - 1)}…` : flat;
+}
+/**
+ * The sentence appended to a mismatch diagnostic. Names the two sides as
+ * producer and consumer (never the probe's internal sent/expected), so the
+ * reader knows which repo to change.
+ */
+export function describeFieldReport(report, sentSide, expectedSide) {
+    const parts = [];
+    if (report.wireApplied) {
+        parts.push(`The ${sentSide}'s type is compared in the form JSON puts on the wire: a value with a toJSON() method (a Date, for example) travels as what it serialises to.`);
+    }
+    if (report.differences.length > 0) {
+        const named = report.differences
+            .map((d) => describeDifference(d, sentSide, expectedSide))
+            .join('; ');
+        const more = report.truncated > 0
+            ? `; and ${report.truncated} further field${report.truncated === 1 ? '' : 's'} differ${report.truncated === 1 ? 's' : ''} (${MAX_NAMED_FIELDS} named here)`
+            : '';
+        parts.push(`Fields that differ: ${named}${more}.`);
+    }
+    return parts.length === 0 ? '' : ` ${parts.join(' ')}`;
+}
+function describeDifference(difference, sentSide, expectedSide) {
+    const at = `'${difference.path}'`;
+    switch (difference.nature) {
+        case 'missing_in_sent':
+            return `${at} is required by the ${expectedSide} and the ${sentSide} does not send it`;
+        case 'extra_in_sent':
+            return `${at} is sent by the ${sentSide} and the ${expectedSide} declares no such field`;
+        case 'optional_in_sent':
+            return `${at} is optional on the ${sentSide} and required by the ${expectedSide}`;
+        case 'optional_in_expected':
+            return `${at} is always sent by the ${sentSide} and optional on the ${expectedSide}`;
+        case 'type_differs':
+            return `${at} is ${difference.sentText} on the ${sentSide} and ${difference.expectedText} on the ${expectedSide}`;
+    }
+}

package/sidecar/dist/src/capture/check-probe.d.ts

@@ -7,6 +7,12 @@
  * conditional-type relation diverges around `any`, and because the compiler's
  * elaborated assignment error is the user-facing mismatch report.
  *
+ * An `http` pair carries a SECOND assignment of the same value in the form JSON
+ * puts on the wire, and that one decides the bucket (see `wireAssignmentLine`):
+ * a payload is serialised before it travels, so the declared types are not what
+ * meet each other. Both questions go to the same judge; nothing here decides a
+ * verdict.
+ *
  * GraphQL pairs additionally unwrap the producer's resolver-return ENVELOPE
  * before the assignment (see the `graphql` branch in `buildProbe`): a GraphQL
  * producer's captured type is the resolver function's return type with
@@ -59,9 +65,23 @@ export interface ProbePlan {
     importLines: number[];
     /** 1-based line -> gate name. TS2344 here => baked-any / unverifiable. */
     gateLines: Map<number, GateName>;
-    /** 1-based line of the value-level assignment. Errors here => incompatible. */
+    /** 1-based line of the value-level assignment of the DECLARED sent type. */
     assignmentLine: number;
+    /**
+     * 1-based line of the second assignment, which sends the same value in the
+     * form JSON puts on the wire (carrick-tools/carrick-cloud#1119). Present for
+     * `http` pairs, whose payload is serialised; absent for every other
+     * protocol, where the declared form is what travels.
+     *
+     * This is the DECISIVE line when present: the comparand short-circuits to
+     * the declared type whenever that already assigns, so an error here means
+     * the shapes disagree in both forms, and no error here means they agree in
+     * the form that actually travels.
+     */
+    wireAssignmentLine?: number;
 }
+/** The assignment line whose diagnostic decides the bucket. */
+export declare function decisiveAssignmentLine(plan: ProbePlan): number;
 /**
  * Build one probe, recording the exact line of every gate and the assignment so
  * the classifier never depends on hard-coded offsets. `packageOf` maps a

package/sidecar/dist/src/capture/check-probe.js

@@ -7,6 +7,12 @@
  * conditional-type relation diverges around `any`, and because the compiler's
  * elaborated assignment error is the user-facing mismatch report.
  *
+ * An `http` pair carries a SECOND assignment of the same value in the form JSON
+ * puts on the wire, and that one decides the bucket (see `wireAssignmentLine`):
+ * a payload is serialised before it travels, so the declared types are not what
+ * meet each other. Both questions go to the same judge; nothing here decides a
+ * verdict.
+ *
  * GraphQL pairs additionally unwrap the producer's resolver-return ENVELOPE
  * before the assignment (see the `graphql` branch in `buildProbe`): a GraphQL
  * producer's captured type is the resolver function's return type with
@@ -63,6 +69,10 @@ export function pairId(spec) {
     ].join('|');
     return fnv1a(key);
 }
+/** The assignment line whose diagnostic decides the bucket. */
+export function decisiveAssignmentLine(plan) {
+    return plan.wireAssignmentLine ?? plan.assignmentLine;
+}
 /**
  * Build one probe, recording the exact line of every gate and the assignment so
  * the classifier never depends on hard-coded offsets. `packageOf` maps a
@@ -148,6 +158,34 @@ export function buildProbe(spec, packageOf) {
     else {
         assignmentLine = push(`const expected: Expected = sent;`);
     }
+    // The JSON wire line (carrick-tools/carrick-cloud#1119). An `http` payload is
+    // serialised before it travels, and `JSON.stringify` writes a value's
+    // `toJSON()` RESULT: a producer's `Date` arrives at the consumer as the
+    // string it serialises to, so comparing the DECLARED `Date` against a
+    // correctly-declared `string` reports a drift that cannot happen. The
+    // transform is applied to the SENT side in BOTH directions, which is where
+    // serialisation happens: a consumer that sends a `Date` in a request body
+    // likewise delivers a string, so a producer declaring `Date` there is a real
+    // mismatch and stays one.
+    //
+    // `WireSent` short-circuits to the declared type when that already assigns,
+    // so a pair that agrees as declared never instantiates the mapped type (no
+    // cost, and no way for the transform to turn an agreeing pair into a
+    // disagreeing one). tsc stays the judge of both forms.
+    let wireAssignmentLine;
+    if (spec.protocol === 'http') {
+        push(`type JsonWireDepth = [never, 0, 1, 2, 3, 4, 5, 6];`);
+        push(`type JsonWire<T, D extends number = 6> = [D] extends [never] ? T : T extends { toJSON: (...args: any[]) => infer R } ? JsonWire<R, JsonWireDepth[D]> : T extends (...args: any[]) => any ? T : T extends object ? { [K in keyof T]: JsonWire<T[K], JsonWireDepth[D]> } : T;`);
+        // Keep the DECLARED type whenever serialising changes nothing observable,
+        // so the compiler's headline still names the real surface alias (the probe
+        // prints `Sent`, which the scrub rewrites) instead of expanding a mapped
+        // type structurally. Only a pair whose payload really is transformed loses
+        // that name — and there the declared name no longer describes what travels.
+        push(`type JsonWireSame<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;`);
+        push(`type WireSent = [Sent] extends [Expected] ? Sent : (JsonWireSame<JsonWire<Sent>, Sent> extends true ? Sent : JsonWire<Sent>);`);
+        push(`declare const sentWire: WireSent;`);
+        wireAssignmentLine = push(`const expectedWire: Expected = sentWire;`);
+    }
     return {
         pairId: id,
         spec,
@@ -159,5 +197,6 @@ export function buildProbe(spec, packageOf) {
         importLines,
         gateLines,
         assignmentLine,
+        wireAssignmentLine,
     };
 }

package/sidecar/dist/src/capture/check.js

@@ -24,7 +24,8 @@ import { classifyPair, parseTscOutput, } from './check-classify.js';
 import { scrubPaths } from './check-scrub.js';
 import { assembleWorkspace, writeProbes, } from './check-workspace.js';
 import { buildPoisonIndexes } from './check-poison.js';
-import { probeDeepFindings } from './check-deep.js';
+import { openProbeProgram, probeDeepFindings } from './check-deep.js';
+import { pairFieldReports } from './check-fields.js';
 function runProcess(command, args, cwd) {
     return new Promise((resolve, reject) => {
         const child = spawn(command, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
@@ -279,7 +280,12 @@ export async function runCheck(opts, onProgress) {
     // carries a member-level any/unknown HERE — after install, where the capture
     // could not look (carrick#450). It sets `resolved` and nothing else; no
     // bucket depends on it.
-    const deepByPair = probeDeepFindings(ws.probesDir, probing);
+    const probeProgram = openProbeProgram(ws.probesDir, probing);
+    const deepByPair = probeDeepFindings(probeProgram, probing);
+    // The same program answers which FIELDS differ on a pair the judge called
+    // incompatible (carrick-tools/carrick-cloud#1118). It names what the verdict
+    // is about; it never decides one.
+    const fieldsByPair = pairFieldReports(probeProgram, probing);
     const verdicts = sortVerdicts([
         ...probing.map((plan) => classifyPair({
             plan,
@@ -287,6 +293,7 @@ export async function runCheck(opts, onProgress) {
             poisonReason,
             scrubCtx,
             deepFindings: deepByPair.get(plan.pairId),
+            fieldReport: fieldsByPair.get(plan.pairId),
         })),
         ...preGated,
         ...unresolved,

package/templates/skills/carrick-census.md

@@ -0,0 +1,89 @@
+---
+name: carrick-census
+description: Use for every place that does X questions, such as every service that reads this environment variable, every handler that checks a permission, or every client of this queue. Pages the Carrick intent index under two wordings and reports what it read and what it could not see.
+---
+
+# Every place that does X
+
+{{SCOPE_NOTE}}
+
+The index produces the list. Your work is to open each row and confirm what it
+does.
+
+## 1. Two wordings
+
+Ask in two wordings. One says what the code is for, the other says how it does
+it. A purpose wording misses a helper whose description names only its
+mechanism, and a mechanism wording misses one described only by its job.
+
+```
+search_by_intent({{SCOPE}}, query: "<what it is for>", also_phrased_as: ["<how it does it>"], compact: true, top_k: 20)
+```
+
+`compact: true` returns locator-only rows, which is the shape a census needs.
+One answer holds both wordings, deduped, with `phrasings` naming them and
+`matched_phrasings` on each row saying which ones reached it. Page it while
+`has_more` is true:
+
+```
+search_by_intent({{SCOPE}}, query: "<the same query>", also_phrased_as: ["<the same second wording>"], compact: true, top_k: 20, offset: <next_offset>)
+```
+
+Where the answer carries no `phrasings`, or the field comes back refused, the
+server answering takes one wording per call. Run the second wording as its own
+paged search.
+
+Stop when `has_more` is false. Lower `similarity_threshold` where the tail of a
+page is still on topic.
+
+## 2. Union
+
+One answer over both wordings is already deduped, and `matched_phrasings` says
+which wordings reached each row. Two answers are joined here, on `file_path` and
+`line_number`, and a row both wordings found is one row. Either way keep
+`retrieved_by` and `similarity`, and keep which wording found each row. A row
+only one wording reached is the row a single search would have lost.
+
+## 3. Receipt
+
+Report these numbers before the list, per query where the field is per query:
+
+- rows read, which is the count you paged to;
+- `total_candidates`, the exact size of the ranked list for that query;
+- `hidden_by_threshold` where the answer carries it: how many rows the floor
+  removed, and `best` where it names the closest of them. A count above zero is
+  the case for one more search at a lower `similarity_threshold`;
+- `total_without_intent`, which is index-wide: functions carrying no intent
+  text, which no search looked at;
+- `total_intent_carried_forward` where the response states it, which are intents
+  describing the code as of an earlier scan.
+
+Then say what the index does not hold for this question. It covers each repo's
+main branch, so a change on a branch is outside it. It indexes functions that
+carry an intent, so a match inside a config file, a template or generated output
+is outside it as well.
+
+## 4. Confirm
+
+Read each row at `file_path`, from `line_number` to `end_line`. Keep the rows
+that do the thing, and drop the rest with one line each saying what they turned
+out to be. `role` on a row says what the scan joined it to, such as a route
+handler or a client, and a route handler for a different operation is not a hit.
+
+## 5. Report
+
+| file:line | function | what it does | found by |
+|---|---|---|---|
+| src/billing/charge.ts:88 | chargeCard | reads the billing key | purpose, mechanism |
+
+Close with the receipt from step 3, so the list is read against what was
+searched.
+
+## 6. Act
+
+Change nothing unless you were asked to. Offer one issue per finding that needs
+work, and file the ones accepted:
+
+```
+gh issue create --title "<concept>: <n> places, <m> need changing" --body "<the table, and the receipt>"
+```