@pikku/inspector 0.12.75 → 0.12.81

package/dist/add/add-feature-flag.js

@@ -0,0 +1,162 @@
+import * as ts from 'typescript';
+import { getPropertyValue } from '../utils/get-property-value.js';
+import { ErrorCode } from '../error-codes.js';
+const SEPARATOR = ':';
+const DEFINE_FEATURE_FLAGS = 'defineFeatureFlags';
+/**
+ * A call is the pikku one when the symbol it resolves to is, whatever the file
+ * chose to call it locally — `import { defineFeatureFlags as declare }` is an
+ * ordinary thing to write, and matching on the callee's text alone both misses
+ * that and claims a same-named local helper.
+ */
+const callsDefineFeatureFlags = (expression, checker) => {
+    if (!ts.isIdentifier(expression))
+        return false;
+    const symbol = checker.getSymbolAtLocation(expression);
+    if (!symbol)
+        return expression.text === DEFINE_FEATURE_FLAGS;
+    // An import specifier names what it imported even when the module itself does
+    // not resolve, which is every project whose deps are not installed yet.
+    const declaration = symbol.declarations?.[0];
+    if (declaration && ts.isImportSpecifier(declaration)) {
+        return ((declaration.propertyName ?? declaration.name).text ===
+            DEFINE_FEATURE_FLAGS);
+    }
+    // Only an imported symbol can be pikku's. A local const of the same name is
+    // a helper the file wrote for itself, and resolving it by name alone would
+    // claim it.
+    if (!(symbol.flags & ts.SymbolFlags.Alias))
+        return false;
+    const resolved = checker.getAliasedSymbol(symbol) ?? symbol;
+    return resolved.name === DEFINE_FEATURE_FLAGS;
+};
+/**
+ * The object literal a declaration's value is written as, following one level
+ * of indirection.
+ *
+ * `{ newCheckout }` and `{ newCheckout: flag }` both read naturally with the
+ * body declared above, and the flag's `anyOf` is extracted by AST — so the
+ * literal has to be found where it was written rather than the property being
+ * skipped, which would declare the flag with no capability constraint at all.
+ */
+const resolveObjectLiteral = (property, checker) => {
+    if (ts.isShorthandPropertyAssignment(property)) {
+        // The name of a shorthand resolves to the property, not to the value it
+        // stands for, which is what `getShorthandAssignmentValueSymbol` is for.
+        return fromSymbol(checker.getShorthandAssignmentValueSymbol(property), checker);
+    }
+    const unwrapped = unwrapAs(property.initializer);
+    if (ts.isObjectLiteralExpression(unwrapped))
+        return unwrapped;
+    if (!ts.isIdentifier(unwrapped))
+        return undefined;
+    return fromSymbol(checker.getSymbolAtLocation(unwrapped), checker);
+};
+const fromSymbol = (symbol, checker) => {
+    const resolved = symbol && symbol.flags & ts.SymbolFlags.Alias
+        ? (checker.getAliasedSymbol(symbol) ?? symbol)
+        : symbol;
+    for (const declaration of resolved?.declarations ?? []) {
+        if (!ts.isVariableDeclaration(declaration) || !declaration.initializer) {
+            continue;
+        }
+        const initializer = unwrapAs(declaration.initializer);
+        if (ts.isObjectLiteralExpression(initializer))
+            return initializer;
+    }
+    return undefined;
+};
+const unwrapAs = (node) => ts.isAsExpression(node) || ts.isSatisfiesExpression(node)
+    ? unwrapAs(node.expression)
+    : node;
+/**
+ * Reads an optional `anyOf: [...]` array of string literals.
+ *
+ * Absent is not the same as empty: absent means no capability constraint, which
+ * is the shape of a pure kill switch, while an empty array satisfies nobody and
+ * is rejected downstream as a declaration mistake.
+ */
+const extractAnyOf = (obj, flagName, logger) => {
+    const prop = obj.properties.find((p) => ts.isPropertyAssignment(p) &&
+        (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+        p.name.text === 'anyOf');
+    if (!prop) {
+        return undefined;
+    }
+    if (!ts.isPropertyAssignment(prop) ||
+        !ts.isArrayLiteralExpression(prop.initializer)) {
+        logger.critical(ErrorCode.INVALID_VALUE, `Feature flag '${flagName}' must declare 'anyOf' as an array literal.`);
+        return undefined;
+    }
+    const scopes = [];
+    for (const element of prop.initializer.elements) {
+        const unwrapped = unwrapAs(element);
+        if (!ts.isStringLiteral(unwrapped)) {
+            logger.critical(ErrorCode.INVALID_VALUE, `Feature flag '${flagName}' lists a scope that is not a string literal. ` +
+                `Scopes are extracted by AST, so a computed value cannot be checked against the declared set.`);
+            continue;
+        }
+        scopes.push(unwrapped.text);
+    }
+    return scopes;
+};
+export const addFeatureFlag = (logger, node, checker, state, _options) => {
+    if (!ts.isCallExpression(node)) {
+        return;
+    }
+    if (!callsDefineFeatureFlags(node.expression, checker)) {
+        return;
+    }
+    const firstArg = node.arguments[0];
+    if (!firstArg) {
+        return;
+    }
+    const unwrapped = unwrapAs(firstArg);
+    if (!ts.isObjectLiteralExpression(unwrapped)) {
+        return;
+    }
+    const sourceFile = node.getSourceFile().fileName;
+    for (const prop of unwrapped.properties) {
+        const shorthand = ts.isShorthandPropertyAssignment(prop);
+        if (!shorthand && !ts.isPropertyAssignment(prop)) {
+            continue;
+        }
+        let name;
+        if (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) {
+            name = prop.name.text;
+        }
+        if (name === undefined) {
+            logger.critical(ErrorCode.NON_LITERAL_WIRE_NAME, 'A feature flag is declared with a key that is not a literal.');
+            continue;
+        }
+        if (name.length === 0) {
+            logger.critical(ErrorCode.INVALID_VALUE, 'A feature flag is declared with an empty name.');
+            continue;
+        }
+        if (name.includes(SEPARATOR)) {
+            logger.critical(ErrorCode.INVALID_VALUE, `Feature flag '${name}' contains the '${SEPARATOR}' separator. ` +
+                `'${SEPARATOR}' delimits scope ids; a flag named like a scope reads as one.`);
+            continue;
+        }
+        const body = resolveObjectLiteral(prop, checker);
+        if (!body) {
+            logger.critical(ErrorCode.INVALID_VALUE, `Feature flag '${name}' must be an object literal, or a variable holding one. ` +
+                `'anyOf' is extracted by AST, so a value this file cannot see would declare the flag with no capability constraint.`);
+            continue;
+        }
+        const anyOf = extractAnyOf(body, name, logger);
+        if (anyOf !== undefined && anyOf.length === 0) {
+            logger.critical(ErrorCode.INVALID_VALUE, `Feature flag '${name}' declares 'anyOf: []'. An empty list satisfies ` +
+                `nobody: omit 'anyOf' for a pure switch, or name the scopes that reveal it.`);
+            continue;
+        }
+        const description = getPropertyValue(body, 'description');
+        state.featureFlags.files.add(sourceFile);
+        state.featureFlags.definitions.push({
+            name,
+            description: description || undefined,
+            anyOf,
+            sourceFile,
+        });
+    }
+};

package/dist/add/add-wire-addon.js

@@ -122,6 +122,7 @@ export function addWireAddon(node, state, logger) {
     logger.debug(`• Found wireAddon: ${name} → ${pkg}`);
     state.rpc.wireAddonDeclarations.set(name, {
         package: pkg,
+        file: node.getSourceFile().fileName,
         rpcEndpoint,
         mcp,
         auth,

package/dist/add/add-wire-remote-addon.js

@@ -57,6 +57,7 @@ export function addWireRemoteAddon(node, state, logger) {
     logger.debug(`• Found wireRemoteAddon: ${name} → ${pkg} (remote)`);
     state.rpc.wireAddonDeclarations.set(name, {
         package: pkg,
+        file: node.getSourceFile().fileName,
         remote: true,
         hasAuth,
         authCredentialId,

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export type { ScenarioInstrumentationFunction } from './add/scenario-instrumenta
 export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
 export type { SerializableInspectorState } from './utils/serialize-inspector-state.js';
 export { filterInspectorState } from './utils/filter-inspector-state.js';
-export { resolveDeployTarget } from './utils/resolve-deploy-target.js';
+export { incompatibleServicesFor, 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';
@@ -24,3 +24,5 @@ export { getFilesAndMethods } from './utils/get-files-and-methods.js';
 export { resolveFunctionMeta } from './utils/resolve-function-meta.js';
 export type { SerializedWorkflowGraph, SerializedWorkflowGraphs, } from './utils/workflow/graph/index.js';
 export { resolveCoreType } from './utils/resolve-core-type.js';
+export { readModuleSpecifiers } from './utils/read-module-specifiers.js';
+export { readTsconfigOutDir } from './utils/read-tsconfig-out-dir.js';

package/dist/index.js

@@ -4,7 +4,7 @@ export { AUTH_HANDLER_FUNC_ID } from './add/add-auth.js';
 export { SCENARIO_INSTRUMENTATION_FUNCTIONS, isScenarioInstrumentationFunction, } from './add/scenario-instrumentation.js';
 export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
 export { filterInspectorState } from './utils/filter-inspector-state.js';
-export { resolveDeployTarget } from './utils/resolve-deploy-target.js';
+export { incompatibleServicesFor, 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';
@@ -13,3 +13,5 @@ export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWork
 export { getFilesAndMethods } from './utils/get-files-and-methods.js';
 export { resolveFunctionMeta } from './utils/resolve-function-meta.js';
 export { resolveCoreType } from './utils/resolve-core-type.js';
+export { readModuleSpecifiers } from './utils/read-module-specifiers.js';
+export { readTsconfigOutDir } from './utils/read-tsconfig-out-dir.js';

package/dist/inspector.js

@@ -160,6 +160,10 @@ export function getInitialInspectorState(rootDir) {
             definitions: [],
             files: new Set(),
         },
+        featureFlags: {
+            definitions: [],
+            files: new Set(),
+        },
         personas: {
             definitions: [],
             files: new Set(),

package/dist/surface/collect-surface.d.ts

@@ -0,0 +1,58 @@
+export type SurfaceKind = 'function' | 'class' | 'interface' | 'type' | 'const' | 'enum' | 'namespace';
+export type SurfaceSymbol = {
+    name: string;
+    kind: SurfaceKind;
+    declaredAt: string;
+    /** Absolute path of the declaring file, or null when it could not be found. */
+    declaredIn: string | null;
+    deprecated: boolean;
+    /** The text of the `@deprecated` tag, when it carries one. */
+    deprecatedReason?: string;
+    /** First paragraph of the symbol's JSDoc. */
+    summary?: string;
+    /** The symbol's JSDoc in full, paragraphs and examples included. */
+    docs?: string;
+    /** The type as the checker prints it, so a caller knows how to call it. */
+    signature?: string;
+    /**
+     * The shape written at the call site, one `name?: type` per entry — the
+     * properties of the object a function takes, or of the type itself. The
+     * signature names that shape; this says what is in it.
+     */
+    members?: SurfaceMember[];
+    /** The `@example` blocks, which the documentation comment leaves out. */
+    examples?: string[];
+    /** The HTTP status an error class is registered with. */
+    status?: number;
+};
+export type SurfaceEntrypoint = {
+    subpath: string;
+    specifier: string;
+    entryFile: string;
+    symbols: SurfaceSymbol[];
+};
+export type CollectSurfaceOptions = {
+    /**
+     * Read the package's `imports` map instead of its `exports` map, taking the
+     * one key given — `#pikku/*` is what an application reaches its generated
+     * leaves through, and it is a private specifier rather than a published one.
+     */
+    importsSubpath?: string;
+    /** Restrict collection to these subpaths, so the program stays small. */
+    subpaths?: string[];
+    /** The snippet regions an `@example snippet: name` resolves against. */
+    snippets?: Map<string, string>;
+};
+export declare class UnknownSnippetError extends Error {
+    constructor(name: string, symbol: string, known: string[]);
+}
+/**
+ * One key of an options object: how it is written, and — where the declaring
+ * type says so — what it means. `schedule: string` is a shape; "a cron
+ * expression" is what a caller actually needs, and only the JSDoc has it.
+ */
+export type SurfaceMember = {
+    line: string;
+    doc?: string;
+};
+export declare const collectSurface: (packageDir: string, { importsSubpath, subpaths, snippets }?: CollectSurfaceOptions) => Promise<SurfaceEntrypoint[]>;