@pikku/cli 0.12.70 → 0.12.72

package/dist/src/functions/commands/scenario.js

@@ -102,21 +102,21 @@ export const scenarioRun = pikkuSessionlessFunc({
             catch (e) {
                 coverageActive = false;
                 logger.warn(`Coverage disabled — '${rpcName}' failed against '${environment}': ${e?.message ?? e}. ` +
-                    `Is the server running with --coverage and the console addon wired?`);
+                    `Is the server running with --coverage and "scaffold.scenarios" enabled in pikku.config.json?`);
                 return null;
             }
         };
         for (const flow of selected) {
             const startedAt = Date.now();
             if (coverageActive) {
-                const reset = await invokeCoverage('console:resetLiveCoverage');
+                const reset = await invokeCoverage('pikkuScenarioResetLiveCoverage');
                 if (reset && reset.enabled === false) {
                     coverageActive = false;
                     logger.warn(`Coverage disabled — '${environment}' is not collecting (start the server with --coverage).`);
                 }
             }
             try {
-                await coverageActor?.invoke('console:resetStubs', null);
+                await coverageActor?.invoke('pikkuScenarioResetStubs', null);
             }
             catch { }
             try {
@@ -148,7 +148,7 @@ export const scenarioRun = pikkuSessionlessFunc({
                 });
             }
             if (coverageActive) {
-                const report = await invokeCoverage('console:takeLiveCoverage');
+                const report = await invokeCoverage('pikkuScenarioTakeLiveCoverage');
                 if (report) {
                     scenarioCoverage[flow.name] = report;
                     const covered = report.functions?.filter((f) => f.status === 'covered' || f.status === 'partial');

package/dist/src/functions/commands/start-coverage.d.ts

@@ -1,4 +1,4 @@
-import { type CoverageService } from '@pikku/core/services';
+import type { CoverageService } from '@pikku/core/services';
 interface CoverageLogger {
     info(message: string): void;
     warn(message: string): void;

package/dist/src/functions/commands/start-coverage.js

@@ -1,6 +1,22 @@
-import { V8CoverageService, IstanbulCoverageService, } from '@pikku/core/services';
+import { V8CoverageService } from '@pikku/core/services/v8-coverage';
+import { IstanbulCoverageService } from '@pikku/core/services/istanbul-coverage';
 import { registerBunCoverageLoader } from './bun-coverage-loader.js';
+import { mapPreciseCoverage, mapLineHitsToReport, } from '../../utils/precise-coverage-map.js';
 const isBunRuntime = () => typeof globalThis.Bun !== 'undefined';
+// The source-map-aware span mapping (and its @jridgewell/trace-mapping
+// dependency) lives in the CLI, not @pikku/core — the scaffolded
+// pikkuScenarioTakeLiveCoverage function reaches it through the optional
+// CoverageService.takeReport, which only the CLI-booted service provides.
+const withTakeReport = (service) => {
+    service.takeReport = async (functionsMeta) => {
+        const snapshot = await service.takeCoverage();
+        if (snapshot.kind === 'line-hits') {
+            return mapLineHitsToReport(snapshot.lineHits, functionsMeta);
+        }
+        return mapPreciseCoverage(snapshot.scripts, snapshot.getScriptSource, functionsMeta);
+    };
+    return service;
+};
 /**
  * Starts the coverage backend for `pikku dev --coverage`: V8 precise coverage
  * on Node, istanbul load-time instrumentation on Bun. Must run before the
@@ -10,14 +26,14 @@ const isBunRuntime = () => typeof globalThis.Bun !== 'undefined';
 export async function startCoverageService(logger, rootDir) {
     if (isBunRuntime()) {
         await registerBunCoverageLoader({ rootDir });
-        logger.info('Istanbul coverage enabled (Bun) — snapshot via console:takeLiveCoverage, reset via console:resetLiveCoverage');
-        return new IstanbulCoverageService();
+        logger.info('Istanbul coverage enabled (Bun) — snapshot via pikkuScenarioTakeLiveCoverage, reset via pikkuScenarioResetLiveCoverage');
+        return withTakeReport(new IstanbulCoverageService());
     }
     const coverageService = new V8CoverageService();
     try {
         await coverageService.start();
-        logger.info('V8 precise coverage enabled — snapshot via console:takeLiveCoverage, reset via console:resetLiveCoverage');
-        return coverageService;
+        logger.info('V8 precise coverage enabled — snapshot via pikkuScenarioTakeLiveCoverage, reset via pikkuScenarioResetLiveCoverage');
+        return withTakeReport(coverageService);
     }
     catch (e) {
         logger.warn(`V8 precise coverage is not supported on this runtime — continuing without coverage: ${e instanceof Error ? e.message : e}`);

package/dist/src/functions/validate/workspace-validate.js

@@ -228,10 +228,6 @@ export async function runWorkspaceValidate(startDir = process.cwd()) {
             info('config-missing', 'packages/functions/src/config.ts not found', join(fnDir, 'src', 'config.ts'), 'Create src/config.ts and export your workspace config factory');
         }
     }
-    const testsDir = join(fnDir, 'tests');
-    if (!existsSync(testsDir)) {
-        info('tests-missing', 'packages/functions/tests/ not found — no function test harness', testsDir, 'Run `pikku tests init` to scaffold the generated function test harness under packages/functions/tests/ (feature files, step defs, and support files)');
-    }
     const sdkDir = join(root, 'packages', 'functions-sdk');
     if (!existsSync(sdkDir)) {
         info('functions-sdk-missing', 'packages/functions-sdk/ not found — generated RPC client and React Query hooks will not be available', sdkDir, 'Create packages/functions-sdk/ as a workspace with src/pikku/ as the generated output root; point clientFiles.rpcMapDeclarationFile and clientFiles.reactQueryFile there');

package/dist/src/functions/wirings/auth/pikku-command-auth.js

@@ -30,7 +30,7 @@ export const pikkuAuth = pikkuSessionlessFunc({
         // has no OAuth providers — still generates its /auth/* wiring.
         if (!state.auth.definition)
             return;
-        const { wiring, secrets, middleware } = serializeAuthGen(state.auth.definition, state.auth.providers, authFile, typesDeclarationFile, packageMappings ?? {}, state.auth.hasUserSessionMiddleware ?? false);
+        const { wiring, secrets, middleware } = serializeAuthGen(state.auth.definition, state.auth.providers, authFile, typesDeclarationFile, packageMappings ?? {}, state.auth.hasUserSessionMiddleware ?? false, Boolean(config.scaffold?.console));
         // The secrets file sits alongside authFile so re-inspection rediscovers it.
         // It is kept separate from the wiring file because the CLI forbids Zod
         // schemas and HTTP wiring (wireHTTPRoutes) in the same file (PKU490).

package/dist/src/functions/wirings/auth/serialize-auth-gen.d.ts

@@ -18,19 +18,4 @@ export interface AuthGenOutput {
      * `session.cookieCache` is enabled (stateless path); undefined otherwise. */
     middleware?: string;
 }
-/**
- * Generates the `auth.gen.ts` (HTTP wiring) and `auth-secrets.gen.ts` (schemas +
- * secret/variable wiring) files from a `pikkuBetterAuth((services) => betterAuth(...))`
- * export.
- *
- * The wiring file side-effect imports the user's auth file (so `pikkuBetterAuth`
- * registers its factory), builds ONE shared sessionless handler that reads the
- * resolved `services.auth` and delegates to better-auth's fetch handler, wires a
- * catch-all `${basePath}{/*splat}` route per method to it, and registers the
- * better-auth session-bridge middleware globally. Provider/plugin metadata for
- * the console is emitted separately as `auth-meta.gen.json` (see
- * serializeAuthMeta). Because this is normal, statically inspectable HTTP
- * wiring, the routes flow through inspection into the deploy manifest (one
- * worker for all auth routes).
- */
-export declare const serializeAuthGen: (definition: AuthDefinition, providers: string[], authFile: string, typesDeclarationFile: string, packageMappings: Record<string, string>, hasUserSessionMiddleware?: boolean) => AuthGenOutput;
+export declare const serializeAuthGen: (definition: AuthDefinition, providers: string[], authFile: string, typesDeclarationFile: string, packageMappings: Record<string, string>, hasUserSessionMiddleware?: boolean, includeConsoleToken?: boolean) => AuthGenOutput;

package/dist/src/functions/wirings/auth/serialize-auth-gen.js

@@ -33,7 +33,22 @@ function variableSchemaName(name, field) {
  * wiring, the routes flow through inspection into the deploy manifest (one
  * worker for all auth routes).
  */
-export const serializeAuthGen = (definition, providers, authFile, typesDeclarationFile, packageMappings, hasUserSessionMiddleware = false) => {
+// External consoles (served from another origin) cannot carry the session
+// cookie, so they authenticate with 'Authorization: Bearer <PIKKU_CONSOLE_TOKEN>'.
+// The expected token resolves through the secrets service per request and the
+// middleware is a no-op while the secret is unset. Emitted into the same
+// addHTTPMiddleware('*') call as the session middleware: the inspector keys
+// route-middleware groups by pattern, so a second '*' registration from another
+// file would silently displace this one in deployed units.
+const consoleTokenMiddlewareLines = () => [
+    `  authBearer({`,
+    `    token: {`,
+    `      secretId: 'PIKKU_CONSOLE_TOKEN',`,
+    `      userSession: { userId: 'pikku-console-token' },`,
+    `    },`,
+    `  }),`,
+];
+export const serializeAuthGen = (definition, providers, authFile, typesDeclarationFile, packageMappings, hasUserSessionMiddleware = false, includeConsoleToken = false) => {
     const known = providers.filter((p) => p in PROVIDER_REGISTRY);
     const basePath = definition.basePath;
     // Side-effect import of the user's auth file so `pikkuBetterAuth` runs and
@@ -132,6 +147,9 @@ export const serializeAuthGen = (definition, providers, authFile, typesDeclarati
         emitStatefulSession
             ? `import { createAuthHandler, betterAuthSession } from '@pikku/better-auth'`
             : `import { createAuthHandler } from '@pikku/better-auth'`,
+        ...(emitStatefulSession && includeConsoleToken
+            ? [`import { authBearer } from '@pikku/core/middleware'`]
+            : []),
         `import '${configImportPath}'`,
         '',
         // createAuthHandler is called once at module load; the exported handler is a
@@ -148,7 +166,12 @@ export const serializeAuthGen = (definition, providers, authFile, typesDeclarati
     if (emitStatefulSession) {
         // Stateful: betterAuthSession calls services.auth(), so it stays here with
         // the auth.wiring import.
-        wiring.push(`addHTTPMiddleware('*', [betterAuthSession()])`, '');
+        if (includeConsoleToken) {
+            wiring.push(`addHTTPMiddleware('*', [`, `  betterAuthSession(),`, ...consoleTokenMiddlewareLines(), `])`, '');
+        }
+        else {
+            wiring.push(`addHTTPMiddleware('*', [betterAuthSession()])`, '');
+        }
     }
     wiring.push(`wireHTTPRoutes({`, `  routes: {`);
     // One catch-all route per method. `{/*splat}` matches both the bare basePath
@@ -172,8 +195,18 @@ export const serializeAuthGen = (definition, providers, authFile, typesDeclarati
             '',
             `import { addHTTPMiddleware } from '${pikkuTypesImportPath}'`,
             `import { betterAuthStatelessSession } from '@pikku/better-auth'`,
+            ...(includeConsoleToken
+                ? [`import { authBearer } from '@pikku/core/middleware'`]
+                : []),
             '',
-            `addHTTPMiddleware('*', [betterAuthStatelessSession()])`,
+            ...(includeConsoleToken
+                ? [
+                    `addHTTPMiddleware('*', [`,
+                    `  betterAuthStatelessSession(),`,
+                    ...consoleTokenMiddlewareLines(),
+                    `])`,
+                ]
+                : [`addHTTPMiddleware('*', [betterAuthStatelessSession()])`]),
             '',
         ];
         output.middleware = middleware.join('\n');

package/dist/src/functions/wirings/console/serialize-console-functions.js

@@ -94,12 +94,6 @@ export const consoleRoutes = defineHTTPRoutes({
       sse: true,
       func: ref('console:streamWorkflowRun'),
     },
-    functionTestsStream: {
-      route: '/function-tests/stream',
-      method: 'get',
-      sse: true,
-      func: ref('console:streamFunctionTests'),
-    },
   },
 })
 

package/dist/src/functions/wirings/scenarios/pikku-command-scenario-functions.d.ts

@@ -0,0 +1 @@
+export declare const pikkuScenarioFunctions: import("#pikku").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/scenarios/pikku-command-scenario-functions.js

@@ -0,0 +1,25 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+import { writeFileInDir } from '../../../utils/file-writer.js';
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
+import { serializeScenarioFunctions } from './serialize-scenario-functions.js';
+export const pikkuScenarioFunctions = pikkuSessionlessFunc({
+    func: async ({ logger, config, variables }) => {
+        const deployCodegenFlag = await variables.get('PIKKU_DEPLOY_CODEGEN');
+        if (deployCodegenFlag === '1') {
+            return false;
+        }
+        if (config.scaffold?.scenarios && config.scenariosFunctionsFile) {
+            const pathToPikkuTypes = getFileImportRelativePath(config.scenariosFunctionsFile, config.typesDeclarationFile, config.packageMappings);
+            await writeFileInDir(logger, config.scenariosFunctionsFile, serializeScenarioFunctions(pathToPikkuTypes, config.scaffold.scenarios === 'auth'));
+            return true;
+        }
+        return false;
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Generating Scenario functions',
+            commandEnd: 'Generated Scenario functions',
+        }),
+    ],
+});

package/dist/src/functions/wirings/scenarios/serialize-scenario-functions.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Generate the scenario instrumentation functions (`pikku scenario` coverage
+ * snapshots and stub-call inspection) into the project scaffold, so scenario
+ * runs work against any server without requiring the console addon.
+ */
+export declare const serializeScenarioFunctions: (pathToPikkuTypes: string, requireAuth?: boolean) => string;

package/dist/src/functions/wirings/scenarios/serialize-scenario-functions.js

@@ -0,0 +1,98 @@
+/**
+ * Generate the scenario instrumentation functions (`pikku scenario` coverage
+ * snapshots and stub-call inspection) into the project scaffold, so scenario
+ * runs work against any server without requiring the console addon.
+ */
+export const serializeScenarioFunctions = (pathToPikkuTypes, requireAuth = true) => {
+    const authFlag = requireAuth ? 'true' : 'false';
+    return `/**
+ * Auto-generated scenario instrumentation functions
+ * Do not edit manually - regenerate with 'npx pikku'
+ */
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { pikkuFunc } from '${pathToPikkuTypes}'
+import {
+  getStubTracker,
+  isTestRun,
+  type CoverageFunctionMeta,
+  type FunctionCoverageReport,
+  type StubCall,
+} from '@pikku/core/services'
+
+export const pikkuScenarioTakeLiveCoverage = pikkuFunc<
+  null,
+  FunctionCoverageReport | null
+>({
+  tags: ['pikku'],
+  title: 'Take Live Coverage',
+  description:
+    'Snapshots the live coverage collected since the server started (or since the last reset) — V8 precise coverage on Node, istanbul instrumentation on Bun — and maps it onto function body spans. Returns null unless the server was started with coverage enabled (pikku dev --coverage).',
+  expose: true,
+  auth: ${authFlag},
+  func: async ({ coverageService, metaService }) => {
+    if (!coverageService?.takeReport || !metaService?.basePath) return null
+    let functionsMeta: Record<string, CoverageFunctionMeta>
+    try {
+      const content = await readFile(
+        join(
+          metaService.basePath,
+          'function',
+          'pikku-functions-meta-verbose.gen.json'
+        ),
+        'utf-8'
+      )
+      functionsMeta = JSON.parse(content)
+    } catch {
+      return null
+    }
+    return await coverageService.takeReport(functionsMeta)
+  },
+})
+
+export const pikkuScenarioResetLiveCoverage = pikkuFunc<
+  null,
+  { enabled: boolean }
+>({
+  tags: ['pikku'],
+  title: 'Reset Live Coverage',
+  description:
+    'Clears V8 precise-coverage call counts so the next takeLiveCoverage snapshot is attributable to a single scenario run. Reports enabled: false when the server was not started with coverage enabled.',
+  expose: true,
+  auth: ${authFlag},
+  func: async ({ coverageService }) => {
+    if (!coverageService) return { enabled: false }
+    await coverageService.reset()
+    return { enabled: true }
+  },
+})
+
+export const pikkuScenarioResetStubs = pikkuFunc<null, { enabled: boolean }>({
+  tags: ['pikku'],
+  title: 'Reset Stubs',
+  description:
+    'Clears recorded stub calls so the next getStubCalls result is attributable to a single scenario run. Reports enabled: false when the server was not started in test mode.',
+  expose: true,
+  auth: ${authFlag},
+  func: async () => {
+    getStubTracker().reset()
+    return { enabled: isTestRun() }
+  },
+})
+
+export const pikkuScenarioGetStubCalls = pikkuFunc<
+  { service?: string },
+  StubCall[]
+>({
+  tags: ['pikku'],
+  title: 'Get Stub Calls',
+  description:
+    'Returns calls recorded against stubbed/spied services (via the stub()/spy() core utils). Empty unless the server records service calls (pikku dev --test).',
+  expose: true,
+  auth: ${authFlag},
+  func: async (_services, data) => {
+    return getStubTracker().getCalls(data?.service ?? undefined)
+  },
+})
+`;
+};

package/dist/src/functions/wirings/workflow/pikku-command-workflow.js

@@ -10,7 +10,7 @@ import { serializeWorkflowBootstrapMap } from './serialize-workflow-bootstrap-ma
 import { serializeWorkflowMeta } from './serialize-workflow-meta.js';
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
 import { stripVerboseFields, hasVerboseFields, } from '../../../utils/strip-verbose-meta.js';
-import { join, dirname } from 'path';
+import { join } from 'path';
 export const pikkuWorkflow = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }, input) => {
         const bootstrap = input?.bootstrap === true;
@@ -67,10 +67,9 @@ export const pikkuWorkflow = pikkuSessionlessFunc({
         if (scenarioActors && Object.keys(scenarioActors).length > 0) {
             const agentMapImportPath = getFileImportRelativePath(config.scenarioActorsFile, config.agentMapDeclarationFile, packageMappings);
             await writeFileInDir(logger, config.scenarioActorsFile, serializeScenarioActors(scenarioActors, agentMapImportPath));
-            // JSON twin for the runtime meta service (console personas view). Lives
-            // next to workflow/meta but NOT inside it — getWorkflowMeta() treats
-            // every workflow/meta/*.gen.json as a workflow.
-            await writeFileInDir(logger, join(dirname(config.scenarioActorsFile), 'scenario-actors.gen.json'), JSON.stringify(scenarioActors, null, 2));
+            // Fixed path getScenarioActorsMeta() reads; kept out of workflow/meta,
+            // which getWorkflowMeta() globs as workflows.
+            await writeFileInDir(logger, join(config.outDir, 'workflow', 'scenario-actors.gen.json'), JSON.stringify(scenarioActors, null, 2));
         }
         await writeFileInDir(logger, workflowMapDeclarationFile, bootstrap
             ? serializeWorkflowBootstrapMap(workflows.meta, workflows.graphMeta)

package/dist/src/functions/workflows/all.workflow.js

@@ -11,6 +11,11 @@ const scaffoldFiles = (config) => {
             file: config.consoleFunctionsFile,
             generator: 'pikkuConsoleFunctions',
         });
+    if (config.scaffold?.scenarios && config.scenariosFunctionsFile)
+        files.push({
+            file: config.scenariosFunctionsFile,
+            generator: 'pikkuScenarioFunctions',
+        });
     if (config.scaffold?.agent && config.publicAgentFile)
         files.push({
             file: config.publicAgentFile,
@@ -126,6 +131,7 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
         await Promise.all([
             workflow.do('Public RPC', 'pikkuPublicRPC', null),
             workflow.do('Console functions', 'pikkuConsoleFunctions', null),
+            workflow.do('Scenario functions', 'pikkuScenarioFunctions', null),
             workflow.do('Events scaffold', 'pikkuEventsScaffold', null),
             workflow.do('Emails', 'pikkuEmails', null),
             workflow.do('Secret definition types', 'pikkuSecretDefinitionTypes', null),

package/dist/src/utils/pikku-cli-config.js

@@ -221,6 +221,9 @@ const _getPikkuCLIConfig = async (logger, configFile = undefined, requiredFields
         if (result.scaffold?.console && !result.consoleFunctionsFile) {
             result.consoleFunctionsFile = join(resolvedScaffoldDir, 'console.gen.ts');
         }
+        if (result.scaffold?.scenarios && !result.scenariosFunctionsFile) {
+            result.scenariosFunctionsFile = join(resolvedScaffoldDir, 'scenarios.gen.ts');
+        }
         if (!result.authFile) {
             result.authFile = join(resolvedScaffoldDir, 'auth.gen.ts');
         }

package/dist/src/utils/precise-coverage-map.d.ts

@@ -0,0 +1,4 @@
+import type { CoverageFunctionMeta, FunctionCoverageReport, ScriptCoverage as ScriptCoverageInput } from '@pikku/core/services';
+export type { ScriptCoverageInput };
+export declare function mapPreciseCoverage(scripts: ScriptCoverageInput[], getScriptSource: (scriptId: string) => Promise<string>, functionsMeta: Record<string, CoverageFunctionMeta>): Promise<FunctionCoverageReport>;
+export declare function mapLineHitsToReport(lineHits: Map<string, Map<number, number>>, functionsMeta: Record<string, CoverageFunctionMeta>): FunctionCoverageReport;

package/dist/src/utils/precise-coverage-map.js

@@ -0,0 +1,176 @@
+// Offsets are mapped through the inline source map rather than line-based
+// statement maps: esbuild emits the whole module on one generated line, which
+// would collapse every statement onto line 1.
+import { fileURLToPath } from 'node:url';
+import { TraceMap, originalPositionFor } from '@jridgewell/trace-mapping';
+const INLINE_SOURCE_MAP = /\/\/# sourceMappingURL=data:application\/json[^,]*;base64,([A-Za-z0-9+/=]+)/;
+function extractInlineSourceMap(source) {
+    const match = source.match(INLINE_SOURCE_MAP);
+    if (!match)
+        return undefined;
+    try {
+        return JSON.parse(Buffer.from(match[1], 'base64').toString('utf-8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function computeLineStarts(source) {
+    const starts = [0];
+    for (let i = 0; i < source.length; i++) {
+        if (source[i] === '\n')
+            starts.push(i + 1);
+    }
+    return starts;
+}
+function offsetToGeneratedPosition(offset, lineStarts) {
+    let low = 0;
+    let high = lineStarts.length - 1;
+    while (low < high) {
+        const mid = (low + high + 1) >> 1;
+        if (lineStarts[mid] <= offset)
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    return { line: low + 1, column: offset - lineStarts[low] };
+}
+function normalizeSourcePath(source) {
+    if (source.startsWith('file://')) {
+        try {
+            return fileURLToPath(source);
+        }
+        catch {
+            return source;
+        }
+    }
+    return source;
+}
+async function scriptToLineCoverage(script, getScriptSource, lineHits) {
+    let scriptPath;
+    try {
+        scriptPath = fileURLToPath(script.url);
+    }
+    catch {
+        return;
+    }
+    let source;
+    try {
+        source = await getScriptSource(script.scriptId);
+    }
+    catch {
+        return;
+    }
+    const sourcemap = extractInlineSourceMap(source);
+    let tracer;
+    if (sourcemap) {
+        try {
+            tracer = new TraceMap(sourcemap);
+        }
+        catch {
+            tracer = undefined;
+        }
+    }
+    const lineStarts = computeLineStarts(source);
+    const mapOffset = (offset) => {
+        const generated = offsetToGeneratedPosition(offset, lineStarts);
+        if (!tracer)
+            return { file: scriptPath, line: generated.line };
+        const original = originalPositionFor(tracer, generated);
+        if (original.source == null || original.line == null)
+            return undefined;
+        const sourceIndex = tracer.sources.indexOf(original.source);
+        const resolved = sourceIndex >= 0
+            ? (tracer.resolvedSources[sourceIndex] ?? original.source)
+            : original.source;
+        return { file: normalizeSourcePath(resolved), line: original.line };
+    };
+    const setHits = (file, from, to, count) => {
+        let hits = lineHits.get(file);
+        if (!hits) {
+            hits = new Map();
+            lineHits.set(file, hits);
+        }
+        for (let line = from; line <= to; line++) {
+            hits.set(line, count);
+        }
+    };
+    for (const fn of script.functions) {
+        // Inner ranges overwrite the outer count (V8 override semantics).
+        for (const range of fn.ranges) {
+            const start = mapOffset(range.startOffset);
+            const end = mapOffset(Math.max(range.startOffset, range.endOffset - 1));
+            if (!start && !end)
+                continue;
+            const file = (start ?? end).file;
+            const from = start?.line ?? end.line;
+            const to = end && end.file === file ? Math.max(end.line, from) : from;
+            setHits(file, from, to, range.count);
+        }
+    }
+}
+export async function mapPreciseCoverage(scripts, getScriptSource, functionsMeta) {
+    const lineHits = new Map();
+    for (const script of scripts) {
+        await scriptToLineCoverage(script, getScriptSource, lineHits);
+    }
+    return mapLineHitsToReport(lineHits, functionsMeta);
+}
+export function mapLineHitsToReport(lineHits, functionsMeta) {
+    const functions = Object.values(functionsMeta)
+        .filter((m) => m.sourceFile && !m.sourceFile.endsWith('.gen.ts'))
+        .map((m) => {
+        const hits = lineHits.get(m.bodySourceFile ?? m.sourceFile);
+        const covered = [];
+        const missed = [];
+        if (hits && m.bodyStart !== undefined && m.bodyEnd !== undefined) {
+            for (const [line, count] of hits) {
+                if (line < m.bodyStart || line > m.bodyEnd)
+                    continue;
+                if (count > 0)
+                    covered.push(line);
+                else
+                    missed.push(line);
+            }
+        }
+        const total = covered.length + missed.length;
+        const ratio = total ? covered.length / total : 0;
+        const status = total === 0
+            ? 'unknown'
+            : covered.length === 0
+                ? 'uncovered'
+                : missed.length === 0
+                    ? 'covered'
+                    : 'partial';
+        return {
+            name: m.name,
+            sourceFile: m.sourceFile,
+            exposed: m.expose !== false,
+            description: m.description ?? null,
+            coveredLines: covered.length,
+            totalLines: total,
+            missedLines: missed.sort((a, b) => a - b),
+            ratio: Number(ratio.toFixed(3)),
+            status,
+        };
+    })
+        .sort((a, b) => a.ratio - b.ratio || a.name.localeCompare(b.name));
+    const summary = {
+        total: functions.length,
+        covered: 0,
+        partial: 0,
+        uncovered: 0,
+        unknown: 0,
+        overallRatio: 0,
+    };
+    for (const f of functions)
+        summary[f.status]++;
+    summary.overallRatio = functions.length
+        ? Number((functions.reduce((a, f) => a + f.ratio, 0) / functions.length).toFixed(3))
+        : 0;
+    return {
+        generatedAt: new Date().toISOString(),
+        summary,
+        functions,
+    };
+}