@pikku/inspector 0.12.60 → 0.12.61

package/dist/add/add-workflow-graph.js

@@ -1,7 +1,7 @@
 import * as ts from 'typescript';
 import { ErrorCode } from '../error-codes.js';
 import { extractStringLiteral } from '../utils/extract-node-value.js';
-function extractAstValue(expr, refParamName, templateParamName) {
+function extractAstValue(expr, refParamName, templateParamName, itemParamName) {
     // `'GET' as const` / parenthesised values wrap the real initializer — see
     // through them or the whole property is silently dropped from the meta.
     while (ts.isAsExpression(expr) || ts.isParenthesizedExpression(expr)) {
@@ -31,6 +31,11 @@ function extractAstValue(expr, refParamName, templateParamName) {
                 const path = args[1] && ts.isStringLiteral(args[1]) ? args[1].text : undefined;
                 return { $ref: nodeId, path };
             }
+            if (itemParamName && callee.text === itemParamName) {
+                const pathArg = expr.arguments[0];
+                const path = pathArg && ts.isStringLiteral(pathArg) ? pathArg.text : undefined;
+                return { $ref: '$item', path };
+            }
             if (templateParamName && callee.text === templateParamName) {
                 const templateStr = expr.arguments[0] && ts.isStringLiteral(expr.arguments[0])
                     ? expr.arguments[0].text
@@ -39,7 +44,7 @@ function extractAstValue(expr, refParamName, templateParamName) {
                 const refs = [];
                 if (refsArg && ts.isArrayLiteralExpression(refsArg)) {
                     for (const el of refsArg.elements) {
-                        const resolved = extractAstValue(el, refParamName, templateParamName);
+                        const resolved = extractAstValue(el, refParamName, templateParamName, itemParamName);
                         if (typeof resolved === 'object' &&
                             resolved !== null &&
                             '$ref' in resolved) {
@@ -64,7 +69,7 @@ function extractAstValue(expr, refParamName, templateParamName) {
         }
     }
     if (ts.isArrayLiteralExpression(expr)) {
-        return expr.elements.map((el) => extractAstValue(el, refParamName, templateParamName));
+        return expr.elements.map((el) => extractAstValue(el, refParamName, templateParamName, itemParamName));
     }
     if (ts.isObjectLiteralExpression(expr)) {
         const obj = {};
@@ -78,7 +83,7 @@ function extractAstValue(expr, refParamName, templateParamName) {
                     : null;
             if (!key)
                 continue;
-            obj[key] = extractAstValue(prop.initializer, refParamName, templateParamName);
+            obj[key] = extractAstValue(prop.initializer, refParamName, templateParamName, itemParamName);
         }
         return obj;
     }
@@ -125,6 +130,11 @@ function extractInputMapping(node, _checker) {
     const templateParamName = node.parameters.length > 1 && ts.isIdentifier(node.parameters[1].name)
         ? node.parameters[1].name.text
         : 'template';
+    // `$item` is appended after `template` so neither existing arrow shape —
+    // `(ref) => ...` nor `(ref, template) => ...` — shifts a parameter.
+    const itemParamName = node.parameters.length > 2 && ts.isIdentifier(node.parameters[2].name)
+        ? node.parameters[2].name.text
+        : undefined;
     const input = {};
     for (const prop of bodyObj.properties) {
         if (!ts.isPropertyAssignment(prop))
@@ -136,13 +146,48 @@ function extractInputMapping(node, _checker) {
                 : null;
         if (!key)
             continue;
-        const value = extractAstValue(prop.initializer, refParamName, templateParamName);
+        const value = extractAstValue(prop.initializer, refParamName, templateParamName, itemParamName);
         if (value !== undefined) {
             input[key] = value;
         }
     }
     return input;
 }
+/**
+ * Extract a `forEach` source, authored either as a bare node id (`'listRows'`)
+ * or as a callback returning a ref (`(ref) => ref('listRows', 'rows')`).
+ */
+function extractForEachConfig(node) {
+    while (ts.isAsExpression(node) || ts.isParenthesizedExpression(node)) {
+        node = node.expression;
+    }
+    if (ts.isStringLiteral(node)) {
+        return { $ref: node.text };
+    }
+    if (ts.isArrowFunction(node)) {
+        const refParamName = node.parameters.length > 0 && ts.isIdentifier(node.parameters[0].name)
+            ? node.parameters[0].name.text
+            : 'ref';
+        let body = node.body;
+        if (ts.isBlock(body)) {
+            for (const stmt of body.statements) {
+                if (ts.isReturnStatement(stmt) && stmt.expression) {
+                    body = stmt.expression;
+                }
+            }
+        }
+        if (!ts.isExpression(body))
+            return undefined;
+        const value = extractAstValue(body, refParamName, undefined);
+        if (typeof value === 'object' &&
+            value !== null &&
+            '$ref' in value &&
+            typeof value.$ref === 'string') {
+            return value;
+        }
+    }
+    return undefined;
+}
 /**
  * Extract next config (string, array, or record)
  */
@@ -301,6 +346,8 @@ function extractGraphFromNewFormat(nodesNode, configNode, checker, state) {
             nodeId,
             rpcName,
             input: {},
+            forEach: undefined,
+            mode: undefined,
             next: undefined,
             onError: undefined,
             retries: undefined,
@@ -326,6 +373,8 @@ function extractGraphFromNewFormat(nodesNode, configNode, checker, state) {
                     nodes[nodeId].next = nodeConfig.next;
                     nodes[nodeId].onError = nodeConfig.onError;
                     nodes[nodeId].input = nodeConfig.input;
+                    nodes[nodeId].forEach = nodeConfig.forEach;
+                    nodes[nodeId].mode = nodeConfig.mode;
                     nodes[nodeId].retries = nodeConfig.retries;
                     nodes[nodeId].retryDelay = nodeConfig.retryDelay;
                     nodes[nodeId].notes = nodeConfig.notes;
@@ -342,6 +391,8 @@ function extractNodeConfigFromObject(obj, checker) {
     let next = undefined;
     let onError = undefined;
     let input = {};
+    let forEach = undefined;
+    let mode = undefined;
     let retries = undefined;
     let retryDelay = undefined;
     let notes = undefined;
@@ -358,6 +409,12 @@ function extractNodeConfigFromObject(obj, checker) {
         else if (propName === 'input') {
             input = extractInputMapping(prop.initializer, checker);
         }
+        else if (propName === 'forEach') {
+            forEach = extractForEachConfig(prop.initializer);
+        }
+        else if (propName === 'mode') {
+            mode = extractStringLiteral(prop.initializer, checker);
+        }
         else if (propName === 'retries') {
             if (ts.isNumericLiteral(prop.initializer)) {
                 retries = Number(prop.initializer.text);
@@ -375,7 +432,7 @@ function extractNodeConfigFromObject(obj, checker) {
             notes = extractStringLiteral(prop.initializer, checker);
         }
     }
-    return { next, onError, input, retries, retryDelay, notes };
+    return { next, onError, input, forEach, mode, retries, retryDelay, notes };
 }
 /**
  * Inspector for pikkuWorkflowGraph() calls

package/dist/add/add-workflow.d.ts

@@ -1,5 +1,5 @@
 import type { AddWiring } from '../types.js';
-import type { WorkflowStepMeta } from '@pikku/core/ecosystem/workflow';
+import type { WorkflowStepMeta } from '@pikku/core/workflow';
 /**
  * Recursively collect all RPC names from workflow steps
  */

package/dist/error-codes.d.ts

@@ -20,7 +20,7 @@ export declare enum ErrorCode {
     CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = "PKU672",
     SCENARIO_HAS_SERVICES = "PKU673",
     EXPECT_EVENTUALLY_SCENARIO_ONLY = "PKU675",
-    SCENARIO_BROWSER_STEP_NEEDS_ACTOR = "PKU677",
+    SCENARIO_STEP_NEEDS_ACTOR = "PKU677",
     SCENARIO_STEP_TARGET_NOT_STATIC = "PKU678",
     SCENARIO_NOT_EXTRACTABLE = "PKU679",
     SCENARIO_HAS_NO_ASSERTION = "PKU680",
@@ -30,6 +30,7 @@ export declare enum ErrorCode {
     COMPLEX_WORKFLOW_NOT_ALLOWED = "PKU643",
     REMOTE_ADDON_NOT_DEV_DEPENDENCY = "PKU338",
     REMOTE_ADDON_AUTH_UNRESOLVED = "PKU339",
+    ADDON_NOT_INSTALLED = "PKU340",
     DB_COLUMN_NAME_TYPE_CONTRADICTION = "PKU480",
     DB_JSON_COLUMN_UNTYPED = "PKU481",
     DB_FORMAT_ON_NON_STRING = "PKU482",
@@ -70,6 +71,7 @@ export declare enum ErrorCode {
     DUPLICATE_CORE_VERSION = "PKU717",
     CORE_VERSION_SKEW = "PKU718",
     SPLIT_TYPE_IDENTITY = "PKU719",
+    SINGLETON_SERVICES_TYPE_UNRESOLVED = "PKU724",
     PII_IN_OUTPUT = "PKU910",
     ADDON_WIRING_NOT_ALLOWED = "PKU920",
     ADDON_CONTRACT_HANDLERS_NOT_ALLOWED = "PKU921",

package/dist/error-codes.js

@@ -22,7 +22,7 @@ export var ErrorCode;
     ErrorCode["CLI_CLIENTSIDE_RENDERER_HAS_SERVICES"] = "PKU672";
     ErrorCode["SCENARIO_HAS_SERVICES"] = "PKU673";
     ErrorCode["EXPECT_EVENTUALLY_SCENARIO_ONLY"] = "PKU675";
-    ErrorCode["SCENARIO_BROWSER_STEP_NEEDS_ACTOR"] = "PKU677";
+    ErrorCode["SCENARIO_STEP_NEEDS_ACTOR"] = "PKU677";
     ErrorCode["SCENARIO_STEP_TARGET_NOT_STATIC"] = "PKU678";
     ErrorCode["SCENARIO_NOT_EXTRACTABLE"] = "PKU679";
     ErrorCode["SCENARIO_HAS_NO_ASSERTION"] = "PKU680";
@@ -33,6 +33,7 @@ export var ErrorCode;
     // Remote addon (wireRemoteAddon) validation
     ErrorCode["REMOTE_ADDON_NOT_DEV_DEPENDENCY"] = "PKU338";
     ErrorCode["REMOTE_ADDON_AUTH_UNRESOLVED"] = "PKU339";
+    ErrorCode["ADDON_NOT_INSTALLED"] = "PKU340";
     // Database schema codegen warnings
     ErrorCode["DB_COLUMN_NAME_TYPE_CONTRADICTION"] = "PKU480";
     ErrorCode["DB_JSON_COLUMN_UNTYPED"] = "PKU481";
@@ -91,6 +92,7 @@ export var ErrorCode;
     ErrorCode["DUPLICATE_CORE_VERSION"] = "PKU717";
     ErrorCode["CORE_VERSION_SKEW"] = "PKU718";
     ErrorCode["SPLIT_TYPE_IDENTITY"] = "PKU719";
+    ErrorCode["SINGLETON_SERVICES_TYPE_UNRESOLVED"] = "PKU724";
     // Data classification errors
     ErrorCode["PII_IN_OUTPUT"] = "PKU910";
     // Addon authoring errors

package/dist/index.d.ts

@@ -12,9 +12,11 @@ export type { SerializableInspectorState } from './utils/serialize-inspector-sta
 export { filterInspectorState } from './utils/filter-inspector-state.js';
 export { resolveDeployTarget } from './utils/resolve-deploy-target.js';
 export { generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
+export { unresolvedSchemaReferences } from './utils/post-process.js';
+export type { SurfaceUsageCounts } from './utils/extract-surface-usage.js';
 export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
 export type { ContractEntry, VersionHashEntry, VersionValidateError, VersionManifest, VersionManifestEntry, } from './utils/contract-hashes.js';
-export type { InspectorFeature, InspectorFeatureEntry, } from './types.js';
+export type { InspectorFeature, InspectorFeatureEntry } from './types.js';
 export { serializeMCPJson } from './utils/serialize-mcp-json.js';
 export type { OpenAPISpecInfo } from './utils/serialize-openapi-json.js';
 export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/index.js';

package/dist/index.js

@@ -6,6 +6,7 @@ export { serializeInspectorState, deserializeInspectorState, } from './utils/ser
 export { filterInspectorState } from './utils/filter-inspector-state.js';
 export { resolveDeployTarget } from './utils/resolve-deploy-target.js';
 export { generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
+export { unresolvedSchemaReferences } from './utils/post-process.js';
 export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
 export { serializeMCPJson } from './utils/serialize-mcp-json.js';
 export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/index.js';

package/dist/inspector.js

@@ -1,6 +1,6 @@
 import * as ts from 'typescript';
 import { performance } from 'perf_hooks';
-import { dirname, resolve } from 'path';
+import { dirname, relative, resolve } from 'path';
 import { visitSetup, visitFunctions, visitRoutes } from './visit.js';
 import { TypesMap } from './types-map.js';
 import { getFilesAndMethods } from './utils/get-files-and-methods.js';
@@ -11,12 +11,13 @@ import { validateExposedFunctionsGated } from './utils/validate-exposed-function
 import { validateTagsResolveToMiddleware } from './utils/validate-tags-resolve-to-middleware.js';
 import { annotateHttpRouteAuth } from './utils/annotate-http-route-auth.js';
 import { generateOpenAPISpec } from './utils/serialize-openapi-json.js';
-import { pikkuState } from '@pikku/core/ecosystem';
+import { pikkuState } from '@pikku/core/state';
 import { resolveLatestVersions } from './utils/resolve-versions.js';
 import { finalizeWorkflows } from './utils/workflow/graph/finalize-workflows.js';
 import { finalizeWorkflowHelperTypes, finalizeWorkflowWires, } from './utils/workflow/graph/finalize-workflow-wires.js';
 import { generateAllSchemas } from './utils/schema-generator.js';
 import { extractSecretUsage } from './utils/extract-secret-usage.js';
+import { accumulateSurfaceUsage, surfaceUsageArea, } from './utils/extract-surface-usage.js';
 import { loadAddonFunctionsMeta, loadAddonSchemas, } from './utils/load-addon-functions-meta.js';
 import { computeContractHashes, extractContractsFromMeta, updateManifest, createEmptyManifest, validateContracts, } from './utils/contract-hashes.js';
 /**
@@ -142,6 +143,7 @@ export function getInitialInspectorState(rootDir) {
             files: new Set(),
             usage: new Map(),
         },
+        surfaceUsage: {},
         credentials: {
             definitions: [],
             files: new Set(),
@@ -299,11 +301,19 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         .sort((a, b) => a.fileName < b.fileName ? -1 : a.fileName > b.fileName ? 1 : 0);
     logger.debug(`Got source files in ${(performance.now() - startSourceFiles).toFixed(2)}ms`);
     const state = getInitialInspectorState(rootDir);
+    const surfaceAreaCache = new Map();
     for (const sourceFile of sourceFiles) {
         const usage = extractSecretUsage(sourceFile);
         if (usage.keys.length > 0 || usage.dynamic.length > 0) {
             state.secrets.usage.set(sourceFile.fileName, usage);
         }
+        // Counted in the sweep that already has this file open. The public surface
+        // is documentation, and documentation may not cost a project a second pass
+        // over its source.
+        accumulateSurfaceUsage(sourceFile, {
+            area: surfaceUsageArea(sourceFile.fileName, rootDir, surfaceAreaCache),
+            file: relative(rootDir, sourceFile.fileName),
+        }, state.surfaceUsage);
     }
     // First sweep: add all functions
     const startSetup = performance.now();

package/dist/types.d.ts

@@ -1,27 +1,29 @@
 import type * as ts from 'typescript';
 import type { SecretUsage } from './utils/extract-secret-usage.js';
-import type { ChannelMessageMeta, ChannelsMeta } from '@pikku/core/ecosystem/channel';
-import type { GatewaysMeta } from '@pikku/core/ecosystem/gateway';
-import type { HTTPWiringsMeta } from '@pikku/core/ecosystem/http';
-import type { ScheduledTasksMeta } from '@pikku/core/ecosystem/scheduler';
-import type { TriggerMeta, TriggerSourceMeta } from '@pikku/core/ecosystem/trigger';
-import type { QueueWorkersMeta } from '@pikku/core/ecosystem/queue';
-import type { WorkflowsMeta } from '@pikku/core/ecosystem/workflow';
-import type { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '@pikku/core/ecosystem/mcp';
-import type { AgentsMeta } from '@pikku/core/ecosystem/agent';
-import type { ScorerMeta } from '@pikku/core/ecosystem/agent-scorer';
-import type { CLIMeta } from '@pikku/core/ecosystem/cli';
-import type { CLICommandMeta } from '@pikku/core/ecosystem/cli';
-import type { NodesMeta } from '@pikku/core/ecosystem/node';
-import type { SecretDefinitions } from '@pikku/core/ecosystem/secret';
-import type { CredentialDefinitions } from '@pikku/core/ecosystem/credential';
-import type { ScopeDefinitions } from '@pikku/core/ecosystem/scope';
-import type { SystemRoleDefinitions } from '@pikku/core/ecosystem/role';
-import type { PersonaDefinitions } from '@pikku/core/ecosystem/persona';
-import type { VariableDefinitions } from '@pikku/core/ecosystem/variable';
+import type { SurfaceUsageCounts } from './utils/extract-surface-usage.js';
+import type { ChannelMessageMeta, ChannelsMeta } from '@pikku/core/channel';
+import type { GatewaysMeta } from '@pikku/core/gateway';
+import type { HTTPWiringsMeta } from '@pikku/core/http';
+import type { ScheduledTasksMeta } from '@pikku/core/scheduler';
+import type { TriggerMeta, TriggerSourceMeta } from '@pikku/core/trigger';
+import type { QueueWorkersMeta } from '@pikku/core/queue';
+import type { WorkflowsMeta } from '@pikku/core/workflow';
+import type { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '@pikku/core/mcp';
+import type { AgentsMeta } from '@pikku/core/agent';
+import type { ScorerMeta } from '@pikku/core/agent-scorer';
+import type { CLIMeta } from '@pikku/core/cli';
+import type { CLICommandMeta } from '@pikku/core/cli';
+import type { NodesMeta } from '@pikku/core/node';
+import type { SecretDefinitions } from '@pikku/core/secret';
+import type { CredentialDefinitions } from '@pikku/core/credential';
+import type { ScopeDefinitions } from '@pikku/core/scope';
+import type { SystemRoleDefinitions } from '@pikku/core/role';
+import type { PersonaDefinitions } from '@pikku/core/persona';
+import type { VariableDefinitions } from '@pikku/core/variable';
 import type { TypesMap } from './types-map.js';
-import type { FunctionsMeta } from '@pikku/core/ecosystem/services';
-import type { FunctionServicesMeta, FunctionWiresMeta, JSONValue } from '@pikku/core/ecosystem/types';
+import type { FunctionsMeta } from '@pikku/core/services';
+import type { FunctionServicesMeta, FunctionWiresMeta } from '@pikku/core/function';
+import type { JSONValue } from '@pikku/core/utils';
 import type { OpenAPISpecInfo } from './utils/serialize-openapi-json.js';
 import type { ErrorCode, CodedDiagnostic } from './error-codes.js';
 import type { VersionManifest, VersionValidateError } from './utils/contract-hashes.js';
@@ -593,6 +595,8 @@ export interface InspectorState {
         /** Secret reads found per source file, keyed by absolute path. */
         usage: Map<string, SecretUsage>;
     };
+    /** How often each `#pikku/*` export is imported, and from where. */
+    surfaceUsage: SurfaceUsageCounts;
     credentials: {
         definitions: CredentialDefinitions;
         files: Set<string>;

package/dist/utils/annotate-http-route-auth.js

@@ -1,3 +1,4 @@
+import { resolveFunctionMeta } from './resolve-function-meta.js';
 /**
  * Resolve, per HTTP route, whether reaching it requires a session.
  *
@@ -22,7 +23,7 @@ export function annotateHttpRouteAuth(state) {
     const gatedPackages = packagesGatedByTheirAddon(state);
     for (const routes of Object.values(state.http?.meta ?? {})) {
         for (const route of Object.values(routes)) {
-            const meta = state.functions.meta[route.refTarget ?? route.pikkuFuncId];
+            const meta = resolveFunctionMeta(state, route.pikkuFuncId);
             route.requiresSession =
                 // A pikkuFunc always requires a session, on every path.
                 meta?.sessionless === false ||

package/dist/utils/check-secret-sinks.js

@@ -38,7 +38,8 @@ const SINKS = [
 export function findRevealedSecretSinks(checker, handler) {
     const violations = [];
     const visit = (node) => {
-        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+        if (ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression)) {
             const sink = describeSink(checker, node.expression);
             if (sink) {
                 for (const arg of node.arguments) {

package/dist/utils/compute-required-schemas.d.ts

@@ -1,4 +1,4 @@
-import type { FunctionsMeta } from '@pikku/core/ecosystem/services';
+import type { FunctionsMeta } from '@pikku/core/services';
 import type { TypesMap } from '../types-map.js';
 import type { SchemaRef } from '../types.js';
 export declare function computeRequiredSchemas(functionsMeta: FunctionsMeta, typesMap: TypesMap, additionalTypes?: string[], schemaLookup?: Map<string, SchemaRef>): Set<string>;

package/dist/utils/contract-hashes.d.ts

@@ -1,5 +1,5 @@
-import type { FunctionsMeta } from '@pikku/core/ecosystem/services';
-import type { JSONValue } from '@pikku/core/ecosystem/types';
+import type { FunctionsMeta } from '@pikku/core/services';
+import type { JSONValue } from '@pikku/core/utils';
 import type { TypesMap } from '../types-map.js';
 import { ErrorCode } from '../error-codes.js';
 export type ContractEntry = {

package/dist/utils/contract-hashes.js

@@ -1,4 +1,4 @@
-import { parseVersionedId } from '@pikku/core/ecosystem/types';
+import { parseVersionedId } from '@pikku/core/utils';
 import { ErrorCode } from '../error-codes.js';
 import { canonicalJSON, hashString } from './hash.js';
 function isHashEntry(v) {

package/dist/utils/extract-function-name.js

@@ -1,7 +1,7 @@
 import * as ts from 'typescript';
 import { createHash } from 'crypto';
 import { relative } from 'path';
-import { formatVersionedId } from '@pikku/core/ecosystem/types';
+import { formatVersionedId } from '@pikku/core/utils';
 /**
  * Deterministic placeholder id for an anonymous/unnamed pikku function or
  * permission. Derived from the call expression's source location (relative path

package/dist/utils/extract-services.d.ts

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import type { FunctionServicesMeta, FunctionWiresMeta } from '@pikku/core/ecosystem/types';
+import type { FunctionServicesMeta, FunctionWiresMeta } from '@pikku/core/function';
 /**
  * Extract services from a function's first parameter destructuring pattern
  */

package/dist/utils/extract-surface-usage.d.ts

@@ -0,0 +1,29 @@
+import ts from 'typescript';
+/**
+ * How often each `#pikku/*` export is imported, the source areas it was
+ * imported from, and the files those imports are written in. Counters only:
+ * this is accumulated during the sweep that already visits every source file,
+ * so nothing here may retain a node.
+ */
+export type SurfaceUsageCounts = Record<string, Record<string, {
+    imports: number;
+    seenIn: string[];
+    files: string[];
+}>>;
+/**
+ * A label a person recognises: the workspace package a file belongs to, or the
+ * top-level source directory it sits under when the project is one package.
+ * The root package is skipped deliberately — naming it would label every file
+ * in a single-package project identically.
+ */
+export declare const surfaceUsageArea: (fileName: string, rootDir: string, cache: Map<string, string | null>) => string;
+/**
+ * Counts the `#pikku/*` imports of one file into `into`. Only the file's own
+ * top-level statements are looked at — an import declaration can appear nowhere
+ * else — so this costs a single pass over the statement list and retains
+ * nothing.
+ */
+export declare const accumulateSurfaceUsage: (sourceFile: ts.SourceFile, { area, file }: {
+    area: string;
+    file: string;
+}, into: SurfaceUsageCounts) => void;

package/dist/utils/extract-surface-usage.js

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync } from 'fs';
+import { basename, dirname, relative, sep } from 'path';
+import ts from 'typescript';
+/**
+ * The leaf a specifier belongs to. `#pikku/workflow` and the deep
+ * `#pikku/workflow/pikku-workflow-types.gen.js` are the same door, so both
+ * count against `#pikku/workflow`.
+ */
+const leafSpecifierOf = (specifier) => {
+    if (!specifier.startsWith('#pikku/'))
+        return null;
+    const leaf = specifier.slice('#pikku/'.length).split('/')[0];
+    // A root-level generated file, e.g. `#pikku/pikku-bootstrap.gen.js`, is not a
+    // leaf and has no editorial entry to count against.
+    if (!leaf || leaf.endsWith('.js'))
+        return null;
+    return `#pikku/${leaf}`;
+};
+const packageNameAt = (directory, cache) => {
+    const cached = cache.get(directory);
+    if (cached !== undefined)
+        return cached;
+    let name = null;
+    const path = `${directory}${sep}package.json`;
+    if (existsSync(path)) {
+        try {
+            name =
+                JSON.parse(readFileSync(path, 'utf8')).name ??
+                    null;
+        }
+        catch {
+            name = null;
+        }
+    }
+    cache.set(directory, name);
+    return name;
+};
+/**
+ * A label a person recognises: the workspace package a file belongs to, or the
+ * top-level source directory it sits under when the project is one package.
+ * The root package is skipped deliberately — naming it would label every file
+ * in a single-package project identically.
+ */
+export const surfaceUsageArea = (fileName, rootDir, cache) => {
+    let directory = dirname(fileName);
+    while (directory.startsWith(rootDir) && directory !== rootDir) {
+        const name = packageNameAt(directory, cache);
+        if (name)
+            return name;
+        directory = dirname(directory);
+    }
+    const [segment] = relative(rootDir, fileName).split(sep);
+    return segment && segment !== basename(fileName) ? segment : basename(rootDir);
+};
+const namesOf = (clause) => {
+    if (!clause)
+        return [];
+    if (ts.isNamedImports(clause) || ts.isNamedExports(clause)) {
+        return clause.elements.map((element) => (element.propertyName ?? element.name).text);
+    }
+    return [];
+};
+/**
+ * Counts the `#pikku/*` imports of one file into `into`. Only the file's own
+ * top-level statements are looked at — an import declaration can appear nowhere
+ * else — so this costs a single pass over the statement list and retains
+ * nothing.
+ */
+export const accumulateSurfaceUsage = (sourceFile, { area, file }, into) => {
+    for (const statement of sourceFile.statements) {
+        let specifier;
+        let names = [];
+        if (ts.isImportDeclaration(statement)) {
+            specifier = statement.moduleSpecifier;
+            names = namesOf(statement.importClause?.namedBindings);
+        }
+        else if (ts.isExportDeclaration(statement) && statement.moduleSpecifier) {
+            specifier = statement.moduleSpecifier;
+            names = namesOf(statement.exportClause);
+        }
+        if (!specifier || names.length === 0 || !ts.isStringLiteral(specifier)) {
+            continue;
+        }
+        const leaf = leafSpecifierOf(specifier.text);
+        if (!leaf)
+            continue;
+        const symbols = (into[leaf] ??= {});
+        for (const name of names) {
+            const usage = (symbols[name] ??= { imports: 0, seenIn: [], files: [] });
+            usage.imports += 1;
+            if (!usage.seenIn.includes(area))
+                usage.seenIn.push(area);
+            if (!usage.files.includes(file))
+                usage.files.push(file);
+        }
+    }
+};