@quotivity/cpq-inventory-core 0.1.0

package/lib/report/types.d.ts

@@ -0,0 +1,146 @@
+import type { OutboundConfig } from '../config/outbound.js';
+import type { BucketId, PhaseId, ReviewReason, Shape, Verdict } from '../types.js';
+export interface ReportRow {
+    rowId: string;
+    label: string;
+    count: number;
+    /** Unit printed after the count when it is not the row's own record ("14 products"). */
+    unit?: string;
+    alive: number;
+    lands: string;
+    verdict: Verdict;
+    shape?: Shape;
+    review?: ReviewReason;
+    /** Present when the row is shown here as a cross-reference; the record is counted in `countedIn`. */
+    crossListed?: {
+        countedIn: BucketId;
+        countedInName: string;
+    };
+    /** Names of the records, in the admin's vocabulary, for the print document and the share summary. */
+    names: string[];
+    details: string[];
+}
+export interface ReportBucket {
+    id: BucketId;
+    name: string;
+    question: string;
+    phase: PhaseId;
+    exists: number;
+    /** null for buckets where liveness has no meaning (Custom code & UI). */
+    alive: number | null;
+    /** Objects whose Alive value is unreliable because of a bulk touch, with the date to print instead. */
+    aliveUnreliable: {
+        object: string;
+        date: string;
+    }[];
+    needsAttention: number;
+    /** Absent (undefined) when the bucket has no review rows — never printed as zero. */
+    review?: number;
+    /** Exists counts mechanisms (non-empty rows) rather than records. */
+    countsMechanisms: boolean;
+    summary: string[];
+    rows: ReportRow[];
+    note: string;
+    partial: boolean;
+    unread: string[];
+}
+export interface MappingRow {
+    id: string;
+    bucket: BucketId;
+    bucketName: string;
+    from: string;
+    to: string;
+    verdict: Verdict;
+    shape?: Shape;
+    /** Records in this org that roll up to the row. */
+    count: number;
+}
+export interface ReviewRow {
+    reason: ReviewReason;
+    subject: string;
+    count: number;
+    question: string;
+    outA: string;
+    outB: string;
+    names: string[];
+}
+export interface Prerequisite {
+    field: string;
+    object: 'SBQQ__Quote__c' | 'SBQQ__QuoteLine__c';
+    need: string;
+    review: boolean;
+}
+export interface NoteCard {
+    head: string;
+    body: string;
+}
+export interface VerdictTile {
+    label: Verdict;
+    meaning: string;
+    count: number;
+    /** Share of verdicted mapping rows, as a percentage. */
+    pct: number;
+}
+export interface ShapeLegendEntry {
+    label: Shape;
+    meaning: string;
+    count: number;
+}
+export interface ReportData {
+    version: string;
+    runId: string;
+    generatedAt: string;
+    org: {
+        name: string;
+        username: string;
+        instanceUrl: string;
+        orgId: string;
+    };
+    window: {
+        months: number;
+        since: string;
+        label: string;
+    };
+    quoteDateField: string;
+    phases: {
+        id: PhaseId;
+        name: string;
+        note: string;
+        buckets: BucketId[];
+    }[];
+    buckets: ReportBucket[];
+    verdictScale: VerdictTile[];
+    shapeLegend: ShapeLegendEntry[];
+    reviewCount: number;
+    mapping: MappingRow[];
+    review: ReviewRow[];
+    notes: NoteCard[];
+    prerequisites: Prerequisite[];
+    seeded: {
+        object: string;
+        count: number;
+    }[];
+    unread: {
+        object: string;
+        reason: string;
+    }[];
+    unscanned: string;
+    residue: {
+        count: number;
+        pct: number;
+    };
+    highlights: string;
+    volume: {
+        quotesByYear: {
+            year: number;
+            total: number;
+            amendRenew: number;
+        }[];
+        quotesInWindow: number;
+        distinctProductsQuoted: number;
+    };
+    outbound: OutboundConfig;
+    fileName: string;
+    sourceUrl: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/report/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/server.d.ts

@@ -0,0 +1,32 @@
+import { type Server } from 'node:http';
+import type { ProgressEvent } from './extract/index.js';
+import type { ReportData } from './report/types.js';
+export type RunStatus = 'idle' | 'running' | 'done' | 'error';
+export interface ServerOptions {
+    /** Runs the analysis. Called at most once, from POST /api/run — never before the gate. */
+    run: (onProgress: (e: ProgressEvent) => void) => Promise<ReportData>;
+    org: {
+        name: string;
+        username: string;
+    };
+    version: string;
+    runId: string;
+    port?: number;
+    host?: string;
+    assetsDir?: string;
+    /** Pre-computed report, for tests and for re-serving a saved run. Skips the gate. */
+    report?: ReportData;
+    log?: (line: string) => void;
+}
+export interface RunningServer {
+    server: Server;
+    url: string;
+    port: number;
+    close: () => Promise<void>;
+    state: () => {
+        status: RunStatus;
+        error?: string;
+    };
+}
+export declare function startServer(opts: ServerOptions): Promise<RunningServer>;
+//# sourceMappingURL=server.d.ts.map

package/lib/server.js

@@ -0,0 +1,185 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { extname, join, resolve } from 'node:path';
+import { outboundConfig } from './config/outbound.js';
+import { ASSETS_DIR, assetsAvailable, buildPrintDocument, MIME } from './report/printDoc.js';
+import { buildShareSummary } from './report/shareSummary.js';
+const HOST = '127.0.0.1';
+const DEFAULT_PORT = 3579;
+export async function startServer(opts) {
+    const host = opts.host ?? HOST;
+    const assetsDir = resolve(opts.assetsDir ?? ASSETS_DIR);
+    const log = opts.log ?? (() => { });
+    let status = opts.report ? 'done' : 'idle';
+    let report = opts.report;
+    let error;
+    const progress = [];
+    const subscribers = new Set();
+    const emit = (e) => {
+        progress.push(e);
+        const payload = `data: ${JSON.stringify(e)}\n\n`;
+        for (const res of subscribers)
+            res.write(payload);
+    };
+    const finish = (kind, detail) => {
+        const payload = `event: ${kind}\ndata: ${JSON.stringify({ detail })}\n\n`;
+        for (const res of subscribers) {
+            res.write(payload);
+            res.end();
+        }
+        subscribers.clear();
+    };
+    const startRun = () => {
+        if (status !== 'idle')
+            return;
+        status = 'running';
+        log('Gate submitted. Reading the org…');
+        opts
+            .run(emit)
+            .then((r) => {
+            report = r;
+            status = 'done';
+            log('Analysis complete.');
+            finish('done');
+        })
+            .catch((err) => {
+            status = 'error';
+            error = err instanceof Error ? err.message : String(err);
+            log(`Analysis failed: ${error}`);
+            finish('error', error);
+        });
+    };
+    const json = (res, code, body) => {
+        res.writeHead(code, {
+            'content-type': 'application/json; charset=utf-8',
+            'cache-control': 'no-store',
+        });
+        res.end(JSON.stringify(body));
+    };
+    const handler = (req, res) => {
+        const url = new URL(req.url ?? '/', `http://${host}`);
+        const path = url.pathname;
+        res.setHeader('x-content-type-options', 'nosniff');
+        res.setHeader('referrer-policy', 'no-referrer');
+        if (path === '/api/state') {
+            return json(res, 200, {
+                status,
+                error,
+                progress,
+                org: opts.org,
+                version: opts.version,
+                runId: opts.runId,
+                outbound: outboundConfig(),
+                assets: assetsAvailable(assetsDir),
+            });
+        }
+        if (path === '/api/run' && req.method === 'POST') {
+            startRun();
+            return json(res, 202, { status });
+        }
+        if (path === '/api/progress') {
+            res.writeHead(200, {
+                'content-type': 'text/event-stream',
+                'cache-control': 'no-store',
+                connection: 'keep-alive',
+            });
+            for (const e of progress)
+                res.write(`data: ${JSON.stringify(e)}\n\n`);
+            if (status === 'done') {
+                res.write('event: done\ndata: {}\n\n');
+                return res.end();
+            }
+            if (status === 'error') {
+                res.write(`event: error\ndata: ${JSON.stringify({ detail: error })}\n\n`);
+                return res.end();
+            }
+            subscribers.add(res);
+            req.on('close', () => subscribers.delete(res));
+            return;
+        }
+        if (path === '/api/report.json') {
+            if (!report)
+                return json(res, 409, { error: status === 'error' ? error : 'analysis has not run' });
+            return json(res, 200, report);
+        }
+        if (path === '/api/share-summary') {
+            if (!report)
+                return json(res, 409, { error: 'analysis has not run' });
+            return json(res, 200, { summary: buildShareSummary(report) });
+        }
+        if (path === '/report' && url.searchParams.get('print') === '1') {
+            if (!report)
+                return json(res, 409, { error: 'analysis has not run' });
+            if (!assetsAvailable(assetsDir))
+                return json(res, 500, { error: 'report assets are missing from this install' });
+            const html = buildPrintDocument(report, assetsDir);
+            res.writeHead(200, {
+                'content-type': 'text/html; charset=utf-8',
+                'cache-control': 'no-store',
+            });
+            return res.end(html);
+        }
+        if (path.startsWith('/api/'))
+            return json(res, 404, { error: 'not found' });
+        // Static assets, with SPA fallback to index.html.
+        if (!assetsAvailable(assetsDir)) {
+            res.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' });
+            return res.end('Report assets are missing from this install. Reinstall the package.');
+        }
+        const clean = decodeURIComponent(path).replace(/^\/+/, '');
+        let file = resolve(assetsDir, clean || 'index.html');
+        if (!file.startsWith(assetsDir)) {
+            res.writeHead(403);
+            return res.end();
+        }
+        if (!existsSync(file) || statSync(file).isDirectory())
+            file = join(assetsDir, 'index.html');
+        const type = MIME[extname(file).toLowerCase()] ?? 'application/octet-stream';
+        res.writeHead(200, {
+            'content-type': type,
+            'cache-control': file.endsWith('index.html') ? 'no-store' : 'public, max-age=3600',
+        });
+        res.end(readFileSync(file));
+    };
+    const server = createServer(handler);
+    const port = await listen(server, host, opts.port ?? DEFAULT_PORT);
+    const address = server.address();
+    const url = `http://${host}:${address.port}/`;
+    return {
+        server,
+        url,
+        port,
+        close: () => new Promise((resolveClose) => {
+            for (const s of subscribers)
+                s.end();
+            subscribers.clear();
+            server.close(() => resolveClose());
+        }),
+        state: () => ({ status, error }),
+    };
+}
+/** Binds 127.0.0.1 only. Detects a taken port and increments, up to 20 tries. */
+async function listen(server, host, start) {
+    for (let port = start; port < start + 20; port++) {
+        const ok = await new Promise((resolveTry) => {
+            const onError = (err) => {
+                server.removeListener('listening', onListening);
+                if (err.code === 'EADDRINUSE' || err.code === 'EACCES')
+                    resolveTry(false);
+                else
+                    throw err;
+            };
+            const onListening = () => {
+                server.removeListener('error', onError);
+                resolveTry(true);
+            };
+            server.once('error', onError);
+            server.once('listening', onListening);
+            server.listen(port, host);
+        });
+        if (ok)
+            return port;
+    }
+    throw new Error(`no free port between ${start} and ${start + 19} on ${host}`);
+}
+//# sourceMappingURL=server.js.map

package/lib/soql.d.ts

@@ -0,0 +1,50 @@
+import { type OrgConnection } from './connection.js';
+/** Detail retrieval cap per object. Headline counts are never constrained by it. */
+export declare const RETRIEVE_CAP = 10000;
+export type ReadStatus = 'ok' | 'absent' | 'unread';
+export interface ObjectRead<T extends object = Record<string, unknown>> {
+    object: string;
+    status: ReadStatus;
+    /** Exact count from the aggregate query (0 when absent or unread). */
+    count: number;
+    records: T[];
+    /** True when the object holds more records than were retrieved. */
+    partial: boolean;
+    /** Why the object is absent or unread. */
+    reason?: string;
+}
+export interface ReadOptions {
+    where?: string;
+    orderBy?: string;
+    cap?: number;
+    tooling?: boolean;
+    /**
+     * Classifier inputs cannot be truncated — a partial set produces wrong bucket assignments.
+     * When set, exceeding the cap throws instead of returning a partial read.
+     */
+    classifierInput?: boolean;
+    /** Objects known to be optional (namespace may be absent). */
+    optional?: boolean;
+}
+export declare class ClassifierInputTooLargeError extends Error {
+    readonly object: string;
+    readonly count: number;
+    constructor(object: string, count: number);
+}
+export declare function soqlDate(d: Date): string;
+export declare function quote(value: string): string;
+export declare function inList(ids: Iterable<string>): string;
+export declare function count(conn: OrgConnection, object: string, where?: string, tooling?: boolean): Promise<number>;
+/**
+ * Reads one object: an aggregate COUNT() for the headline figure, then the records up to the cap.
+ * Missing objects (a namespace that is not installed) come back `absent`; transport failures after
+ * retries come back `unread`. Neither is ever reported as zero.
+ */
+export declare function readObject<T extends object = Record<string, unknown>>(conn: OrgConnection, object: string, fields: readonly string[], opts?: ReadOptions): Promise<ObjectRead<T>>;
+/** Aggregate query returning grouped rows; absent/unread collapse to an empty list. */
+export declare function aggregate<T extends object>(conn: OrgConnection, soql: string, tooling?: boolean): Promise<{
+    rows: T[];
+    status: ReadStatus;
+    reason?: string;
+}>;
+//# sourceMappingURL=soql.d.ts.map

package/lib/soql.js

@@ -0,0 +1,76 @@
+import { errorText, isMissingObjectError, withRetry } from './connection.js';
+/** Detail retrieval cap per object. Headline counts are never constrained by it. */
+export const RETRIEVE_CAP = 10_000;
+export class ClassifierInputTooLargeError extends Error {
+    object;
+    count;
+    constructor(object, count) {
+        super(`${object} holds ${count} records, more than the ${RETRIEVE_CAP} the classifier can read in full. The run stops rather than classifying a partial set.`);
+        this.object = object;
+        this.count = count;
+        this.name = 'ClassifierInputTooLargeError';
+    }
+}
+export function soqlDate(d) {
+    return d.toISOString();
+}
+export function quote(value) {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+export function inList(ids) {
+    return `(${[...ids].map(quote).join(',')})`;
+}
+export async function count(conn, object, where, tooling = false) {
+    const soql = `SELECT COUNT() FROM ${object}${where ? ` WHERE ${where}` : ''}`;
+    const res = await withRetry(() => conn.query(soql, { tooling }));
+    return res.totalSize;
+}
+function empty(object, status, reason) {
+    return { object, status, count: 0, records: [], partial: false, reason };
+}
+/**
+ * Reads one object: an aggregate COUNT() for the headline figure, then the records up to the cap.
+ * Missing objects (a namespace that is not installed) come back `absent`; transport failures after
+ * retries come back `unread`. Neither is ever reported as zero.
+ */
+export async function readObject(conn, object, fields, opts = {}) {
+    const cap = opts.cap ?? RETRIEVE_CAP;
+    const where = opts.where ? ` WHERE ${opts.where}` : '';
+    const orderBy = opts.orderBy ? ` ORDER BY ${opts.orderBy}` : '';
+    try {
+        const total = await count(conn, object, opts.where, opts.tooling);
+        if (opts.classifierInput && total > cap)
+            throw new ClassifierInputTooLargeError(object, total);
+        if (total === 0)
+            return { object, status: 'ok', count: 0, records: [], partial: false };
+        const soql = `SELECT ${fields.join(', ')} FROM ${object}${where}${orderBy} LIMIT ${cap}`;
+        const res = await withRetry(() => conn.query(soql, { tooling: opts.tooling }));
+        return {
+            object,
+            status: 'ok',
+            count: total,
+            records: res.records,
+            partial: total > res.records.length,
+        };
+    }
+    catch (err) {
+        if (err instanceof ClassifierInputTooLargeError)
+            throw err;
+        if (isMissingObjectError(err))
+            return empty(object, 'absent', errorText(err));
+        return empty(object, 'unread', errorText(err));
+    }
+}
+/** Aggregate query returning grouped rows; absent/unread collapse to an empty list. */
+export async function aggregate(conn, soql, tooling = false) {
+    try {
+        const res = await withRetry(() => conn.query(soql, { tooling }));
+        return { rows: res.records, status: 'ok' };
+    }
+    catch (err) {
+        if (isMissingObjectError(err))
+            return { rows: [], status: 'absent', reason: errorText(err) };
+        return { rows: [], status: 'unread', reason: errorText(err) };
+    }
+}
+//# sourceMappingURL=soql.js.map

package/lib/summary.d.ts

@@ -0,0 +1,14 @@
+import type { Classification } from './classify/index.js';
+import type { Extraction } from './extract/index.js';
+import type { BucketId } from './types.js';
+export interface SummaryInput {
+    ex: Extraction;
+    cl: Classification;
+    rowCount: (rowId: string) => number;
+    bucketAlive: (id: BucketId) => number | null;
+    mechanisms: number;
+}
+/** One line per bucket, in the admin's vocabulary, counts first. */
+export declare function summaryLines(id: BucketId, s: SummaryInput): string[];
+export declare function bucketNote(id: BucketId, s: SummaryInput): string;
+//# sourceMappingURL=summary.d.ts.map

package/lib/summary.js

@@ -0,0 +1,143 @@
+const n = (v) => v.toLocaleString('en-US');
+const plural = (v, one, many = `${one}s`) => `${n(v)} ${v === 1 ? one : many}`;
+/** One line per bucket, in the admin's vocabulary, counts first. */
+export function summaryLines(id, s) {
+    const { ex, cl, rowCount } = s;
+    const f = cl.facts;
+    const years = ex.windowMonths === 12 ? 'the last 12 months' : `the trailing ${ex.windowMonths} months`;
+    switch (id) {
+        case 'catalog': {
+            const cur = f.multiCurrency
+                ? `${f.currencies.length} currencies enabled.`
+                : 'single currency.';
+            return [
+                `${plural(ex.product2.count, 'active product')} across ${plural(ex.pricebook2.count, 'price book')}, ${cur}`,
+                `${n(f.productsNeverQuoted)} never appeared on a quote line in ${years}.`,
+            ];
+        }
+        case 'configuration': {
+            const dormant = ex.productFeature.records.filter((r) => !r.LastModifiedDate || r.LastModifiedDate < ex.since).length;
+            const filters = rowCount('cfg.filterRules');
+            return [
+                `${plural(f.bundles, 'bundle')}, ${plural(f.featureCount, 'bundle option')}, deepest ${plural(f.nestingDepth, 'level')}.`,
+                `${n(dormant)} not configured since ${ex.since.slice(0, 4)}. ${n(filters)} use dynamic option sets.`,
+            ];
+        }
+        case 'discovery':
+            return [
+                `${plural(f.attributeCount, 'configuration attribute')}, ${plural(ex.quoteProcess.count, 'guided selling process', 'guided selling processes')}, ${plural(ex.processInput.count, 'process input')}.`,
+                `${plural(rowCount('disc.priceRulesDefaulting'), 'price rule')} exist only to default a field.`,
+            ];
+        case 'price': {
+            const qcp = ex.customScript.count;
+            return [
+                `${n(s.mechanisms)} distinct ${s.mechanisms === 1 ? 'way' : 'ways'} a price reaches a line.`,
+                qcp
+                    ? `${n(qcp)} of the calculation path${qcp === 1 ? ' runs' : 's run'} through a Quote Calculator Plugin.`
+                    : 'None of them run through a Quote Calculator Plugin.',
+            ];
+        }
+        case 'discounting': {
+            const above = rowCount('dsc.quoteScope') + rowCount('dsc.groupScope');
+            return [
+                `${plural(ex.discountSchedule.count, 'discount schedule')}, ${plural(f.discountTierCount, 'tier')}, ${plural(ex.contractedPrice.count, 'contracted price')}.`,
+                `${n(above)} schedule${above === 1 ? '' : 's'} aggregate above the line rather than on it.`,
+            ];
+        }
+        case 'guardrails': {
+            const rules = rowCount('grd.validation') +
+                rowCount('grd.alert') +
+                rowCount('grd.quoteScope') +
+                rowCount('grd.platformValidation');
+            const floors = rowCount('grd.floorCeiling');
+            const alive = s.bucketAlive('guardrails');
+            return [
+                `${plural(rules, 'rule')} that stop or warn a rep.${alive != null ? ` ${n(alive)} touched in ${years}.` : ''}`,
+                `${plural(floors, 'margin floor or ceiling')} ${floors === 1 ? 'is' : 'are'} computed by a price rule a validation rule then tests.`,
+            ];
+        }
+        case 'approvals': {
+            const cycle = f.medianApprovalCycleDays != null
+                ? ` Median cycle ${f.medianApprovalCycleDays.toFixed(1)} days.`
+                : '';
+            const engines = f.advancedApprovalsInstalled
+                ? f.nativeApprovalProcesses
+                    ? `Advanced Approvals and ${plural(f.nativeApprovalProcesses, 'native approval process', 'native approval processes')} are both live.`
+                    : 'Advanced Approvals is the only engine in use.'
+                : f.nativeApprovalProcesses
+                    ? `Advanced Approvals is not installed. ${plural(f.nativeApprovalProcesses, 'native approval process', 'native approval processes')} on Quote or Opportunity.`
+                    : 'Advanced Approvals is not installed and no native approval process runs on Quote or Opportunity.';
+            return [
+                `${plural(ex.approvalRule.count, 'approval rule')}, ${plural(ex.approvalChain.count, 'chain')}, ${plural(f.approverCount, 'approver')}.${cycle}`,
+                engines,
+            ];
+        }
+        case 'output': {
+            const stale = ex.quoteTemplate.records.filter((r) => !r.LastModifiedDate || r.LastModifiedDate < ex.since).length;
+            return [
+                `${plural(ex.quoteTemplate.count, 'template')}, ${plural(f.templateSectionCount, 'section')}, ${plural(ex.lineColumn.count, 'line column')}, ${plural(ex.quoteTerm.count, 'quote term')}.`,
+                `${n(stale)} template${stale === 1 ? ' has' : 's have'} not been touched since ${ex.since.slice(0, 4)}.`,
+            ];
+        }
+        case 'lifecycle': {
+            const share = f.amendRenewShareLastYear != null && f.lastYear != null
+                ? `${Math.round(f.amendRenewShareLastYear * 100)}% of ${f.lastYear}'s quotes were renewals or amendments.`
+                : 'No quotes dated last year, so the renewal share cannot be measured.';
+            return [
+                `${plural(ex.contractActive, 'active contract')}, ${plural(f.subscriptionCount, 'subscription')}.`,
+                share,
+            ];
+        }
+        case 'code':
+            return [
+                `${plural(ex.customScript.count, 'Quote Calculator Plugin')}, ${plural(ex.apexTrigger.count, 'trigger')}, ${plural(ex.customAction.count, 'custom action')}, ${plural(rowCount('code.ui'), 'UI customisation')}.`,
+                'Named and flagged for review. Not interpreted.',
+            ];
+    }
+}
+export function bucketNote(id, s) {
+    const { ex, cl } = s;
+    const f = cl.facts;
+    switch (id) {
+        case 'catalog':
+            return 'Counts come from aggregate queries. PricebookEntry records are never retrieved — a product with no price in a currency is a catalogue data problem, not a migration finding.';
+        case 'configuration': {
+            const nested = s.rowCount('cfg.optionsNested');
+            return nested
+                ? `Nesting has no target — Quotivity bundles are one level deep, so ${n(nested)} option product${nested === 1 ? '' : 's'} ha${nested === 1 ? 's' : 've'} to be flattened or split.`
+                : 'No nested bundles. Every option product is a leaf, which is the shape Quotivity bundles expect.';
+        }
+        case 'discovery':
+            return 'Attributes split by whether the answer is pushed onto product options — that decides which of the two destinations applies.';
+        case 'price':
+            return `This bucket counts mechanisms, not records. ${s.mechanisms > 6 ? `${n(s.mechanisms)} is high — most orgs run three or four.` : 'Most orgs run three or four.'}`;
+        case 'discounting':
+            return `${plural(f.discountTierCount, 'tier')} are read but not counted as constructs — they belong to their schedule. Tier bounds are half-open in CPQ and stay that way on import.`;
+        case 'guardrails': {
+            const seeded = ex.validationRule.records.length;
+            return `Platform validation rules on CPQ objects are counted only when admin-authored (${n(seeded)} here). Package-owned rules are excluded by namespace.`;
+        }
+        case 'approvals':
+            return f.advancedApprovalsInstalled && f.nativeApprovalProcesses
+                ? 'Both engines are running. A SOQL-only inventory would have missed the native processes entirely.'
+                : 'Native approval processes are read from ProcessDefinition, so a native-only org is not reported as zero.';
+        case 'output':
+            return 'Templates are authored fresh rather than imported — same document, no import file. That is true of a move to Revenue Cloud Advanced too.';
+        case 'lifecycle':
+            return f.amendRenewShareLastYear != null && f.amendRenewShareLastYear >= 0.5
+                ? 'Renewals and amendments are the majority of quoting volume here, so this bucket carries more weight than its record count suggests.'
+                : 'Contracts and subscriptions carry to HubSpot Contracts; orders and assets have no target.';
+        case 'code': {
+            const seeded = Object.entries(ex.seeded)
+                .filter(([o]) => /CustomAction|CustomScript/.test(o))
+                .map(([, c]) => c)
+                .reduce((a, b) => a + b, 0);
+            const names = Object.keys(f.qcpHooks);
+            const qcpNote = names.length
+                ? ` ${names.join(', ')} — ${names.length > 3 ? 'several means pricing outgrew the rules engine years ago, itself a finding.' : 'most orgs have zero to three.'}`
+                : '';
+            return `Package-owned records are excluded: ${n(seeded)} custom actions and scripts shipped with CPQ, plus every namespaced trigger, button, layout and record page.${qcpNote}`;
+        }
+    }
+}
+//# sourceMappingURL=summary.js.map

package/lib/types.d.ts

@@ -0,0 +1,22 @@
+/** Verdict scale from the spec. "Further review" is not a verdict but travels in the same field. */
+export type Verdict = 'Clear path' | 'Degraded' | 'No target' | 'Further review';
+export type Shape = '1:1' | 'Fan-out' | 'Rebuild';
+export type ReviewReason = 'Unread' | 'Intent';
+export type BucketId = 'catalog' | 'configuration' | 'discovery' | 'price' | 'discounting' | 'guardrails' | 'approvals' | 'output' | 'lifecycle' | 'code';
+export interface BucketDef {
+    id: BucketId;
+    name: string;
+    question: string;
+    phase: PhaseId;
+}
+export type PhaseId = 'before' | 'quote' | 'after' | 'outside';
+export interface PhaseDef {
+    id: PhaseId;
+    name: string;
+    note: string;
+    buckets: BucketId[];
+}
+export declare const BUCKETS: readonly BucketDef[];
+export declare const PHASES: readonly PhaseDef[];
+export declare function bucketDef(id: BucketId): BucketDef;
+//# sourceMappingURL=types.d.ts.map