@pikku/inspector 0.11.2 → 0.12.0

package/dist/utils/compute-required-schemas.js

@@ -0,0 +1,41 @@
+const PRIMITIVE_TYPES = new Set([
+    'boolean',
+    'string',
+    'number',
+    'null',
+    'undefined',
+    'void',
+    'any',
+    'unknown',
+    'never',
+]);
+export function computeRequiredSchemas(functionsMeta, typesMap, additionalTypes, schemaLookup) {
+    return new Set([
+        ...Object.values(functionsMeta)
+            .map(({ inputs, outputs }) => {
+            const types = [];
+            if (inputs?.[0]) {
+                try {
+                    types.push(typesMap.getUniqueName(inputs[0]));
+                }
+                catch {
+                    types.push(inputs[0]);
+                }
+            }
+            if (outputs?.[0]) {
+                try {
+                    types.push(typesMap.getUniqueName(outputs[0]));
+                }
+                catch {
+                    types.push(outputs[0]);
+                }
+            }
+            return types;
+        })
+            .flat()
+            .filter((s) => !!s && !PRIMITIVE_TYPES.has(s)),
+        ...typesMap.customTypes.keys(),
+        ...(additionalTypes || []),
+        ...(schemaLookup ? Array.from(schemaLookup.keys()) : []),
+    ]);
+}

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

@@ -0,0 +1,35 @@
+import { FunctionsMeta, JSONValue } from '@pikku/core';
+import { TypesMap } from '../types-map.js';
+import { ErrorCode } from '../error-codes.js';
+export type ContractEntry = {
+    functionKey: string;
+    version: number;
+    contractHash: string;
+};
+export type VersionValidateError = {
+    code: ErrorCode;
+    message: string;
+};
+export type VersionManifestEntry = {
+    latest: number;
+    versions: Record<string, string>;
+};
+export type VersionManifest = {
+    manifestVersion: 1;
+    contracts: Record<string, VersionManifestEntry>;
+};
+export declare function createEmptyManifest(): VersionManifest;
+export declare function serializeManifest(manifest: VersionManifest): string;
+export declare function computeContractHash(data: {
+    functionKey: string;
+    inputSchema: unknown;
+    outputSchema: unknown;
+}): string;
+export declare function buildCurrentContracts(functionsMeta: FunctionsMeta, allSchemas: Record<string, JSONValue>, typesMap: TypesMap): Map<string, ContractEntry>;
+export declare function computeContractHashes(allSchemas: Record<string, JSONValue>, typesMap: TypesMap, functionsMeta: FunctionsMeta): Map<string, ContractEntry>;
+export declare function validateContracts(manifest: VersionManifest, currentContracts: Map<string, ContractEntry>): {
+    valid: boolean;
+    errors: VersionValidateError[];
+};
+export declare function updateManifest(existing: VersionManifest, currentContracts: Map<string, ContractEntry>): VersionManifest;
+export declare function extractContractsFromMeta(functionsMeta: FunctionsMeta): Map<string, ContractEntry>;

package/dist/utils/contract-hashes.js

@@ -0,0 +1,202 @@
+import { parseVersionedId } from '@pikku/core';
+import { ErrorCode } from '../error-codes.js';
+import { canonicalJSON, hashString } from './hash.js';
+export function createEmptyManifest() {
+    return {
+        manifestVersion: 1,
+        contracts: {},
+    };
+}
+export function serializeManifest(manifest) {
+    const sortedContracts = {};
+    for (const key of Object.keys(manifest.contracts).sort()) {
+        const entry = manifest.contracts[key];
+        const sortedVersions = {};
+        const numericKeys = Object.keys(entry.versions)
+            .map(Number)
+            .sort((a, b) => a - b);
+        for (const vk of numericKeys) {
+            sortedVersions[String(vk)] = entry.versions[String(vk)];
+        }
+        sortedContracts[key] = {
+            latest: entry.latest,
+            versions: sortedVersions,
+        };
+    }
+    const sorted = {
+        manifestVersion: manifest.manifestVersion,
+        contracts: sortedContracts,
+    };
+    return JSON.stringify(sorted, null, 2) + '\n';
+}
+export function computeContractHash(data) {
+    return hashString(canonicalJSON(data), 16);
+}
+function resolveSchema(typeNames, allSchemas, typesMap) {
+    if (!typeNames) {
+        return null;
+    }
+    const filtered = typeNames.filter((n) => n !== 'void');
+    if (filtered.length === 0) {
+        return null;
+    }
+    const parts = [];
+    for (const name of filtered) {
+        let key;
+        try {
+            key = typesMap.getUniqueName(name);
+        }
+        catch {
+            key = name;
+        }
+        const schema = allSchemas[key];
+        if (schema) {
+            parts.push(schema);
+        }
+    }
+    if (parts.length === 0) {
+        return null;
+    }
+    return parts.length === 1 ? parts[0] : parts;
+}
+export function buildCurrentContracts(functionsMeta, allSchemas, typesMap) {
+    const result = new Map();
+    for (const [funcId, meta] of Object.entries(functionsMeta)) {
+        if (meta.remote === true) {
+            continue;
+        }
+        const parsed = parseVersionedId(funcId);
+        const functionKey = parsed.baseName;
+        const version = parsed.version ?? meta.version ?? 1;
+        const inputSchema = resolveSchema(meta.inputs, allSchemas, typesMap);
+        const outputSchema = resolveSchema(meta.outputs, allSchemas, typesMap);
+        const contractHash = computeContractHash({
+            functionKey,
+            inputSchema,
+            outputSchema,
+        });
+        result.set(funcId, { functionKey, version, contractHash });
+    }
+    return result;
+}
+export function computeContractHashes(allSchemas, typesMap, functionsMeta) {
+    const contracts = buildCurrentContracts(functionsMeta, allSchemas, typesMap);
+    for (const [funcId, entry] of contracts) {
+        const meta = functionsMeta[funcId];
+        if (meta) {
+            meta.contractHash = entry.contractHash;
+        }
+    }
+    return contracts;
+}
+function groupByFunctionKey(contracts) {
+    const grouped = new Map();
+    for (const entry of contracts.values()) {
+        const existing = grouped.get(entry.functionKey) ?? [];
+        existing.push(entry);
+        grouped.set(entry.functionKey, existing);
+    }
+    return grouped;
+}
+export function validateContracts(manifest, currentContracts) {
+    const errors = [];
+    const grouped = groupByFunctionKey(currentContracts);
+    const reportedKeys = new Set();
+    for (const [functionKey, entries] of grouped) {
+        const manifestEntry = manifest.contracts[functionKey];
+        if (!manifestEntry) {
+            continue;
+        }
+        for (const { version, contractHash } of entries) {
+            const existingHash = manifestEntry.versions[String(version)];
+            if (existingHash !== undefined) {
+                if (existingHash !== contractHash) {
+                    reportedKeys.add(`${functionKey}@${version}`);
+                    errors.push({
+                        code: ErrorCode.FUNCTION_VERSION_MODIFIED,
+                        message: `Contract for ${functionKey}@v${version} has changed (recorded: ${existingHash}, current: ${contractHash}). Existing versions are immutable.`,
+                    });
+                }
+            }
+            else {
+                if (version <= manifestEntry.latest) {
+                    errors.push({
+                        code: ErrorCode.VERSION_REGRESSION_OR_CONFLICT,
+                        message: `Version ${version} for ${functionKey} is <= latest (${manifestEntry.latest}) but not recorded. Possible merge conflict.`,
+                    });
+                }
+                else if (version > manifestEntry.latest + 1) {
+                    errors.push({
+                        code: ErrorCode.VERSION_GAP_NOT_ALLOWED,
+                        message: `Version ${version} for ${functionKey} skips versions. Latest is ${manifestEntry.latest}, next must be ${manifestEntry.latest + 1}.`,
+                    });
+                }
+            }
+        }
+    }
+    for (const [functionKey, manifestEntry] of Object.entries(manifest.contracts)) {
+        const latestHash = manifestEntry.versions[String(manifestEntry.latest)];
+        const currentEntries = grouped.get(functionKey);
+        if (!currentEntries) {
+            continue;
+        }
+        const currentLatest = currentEntries.find((e) => e.version === manifestEntry.latest);
+        if (currentLatest &&
+            currentLatest.contractHash !== latestHash &&
+            !reportedKeys.has(`${functionKey}@${manifestEntry.latest}`)) {
+            errors.push({
+                code: ErrorCode.CONTRACT_CHANGED_REQUIRES_BUMP,
+                message: `Contract for ${functionKey} changed. Set \`version: ${manifestEntry.latest + 1}\` on the function or run 'pikku versions update'.`,
+            });
+        }
+    }
+    for (const [functionKey, manifestEntry] of Object.entries(manifest.contracts)) {
+        const numericKeys = Object.keys(manifestEntry.versions).map(Number);
+        if (numericKeys.length === 0) {
+            continue;
+        }
+        const maxVersion = Math.max(...numericKeys);
+        if (manifestEntry.latest !== maxVersion) {
+            errors.push({
+                code: ErrorCode.MANIFEST_INTEGRITY_ERROR,
+                message: `Manifest integrity error for ${functionKey}: latest field (${manifestEntry.latest}) inconsistent with version keys (max: ${maxVersion}).`,
+            });
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+export function updateManifest(existing, currentContracts) {
+    const manifest = {
+        manifestVersion: existing.manifestVersion,
+        contracts: JSON.parse(JSON.stringify(existing.contracts)),
+    };
+    const grouped = groupByFunctionKey(currentContracts);
+    for (const [functionKey, entries] of grouped) {
+        if (!manifest.contracts[functionKey]) {
+            manifest.contracts[functionKey] = { latest: 0, versions: {} };
+        }
+        const entry = manifest.contracts[functionKey];
+        for (const { version, contractHash } of entries) {
+            entry.versions[String(version)] = contractHash;
+            entry.latest = Math.max(entry.latest, version);
+        }
+    }
+    return manifest;
+}
+export function extractContractsFromMeta(functionsMeta) {
+    const result = new Map();
+    for (const [funcId, meta] of Object.entries(functionsMeta)) {
+        if (meta.remote === true || !meta.contractHash) {
+            continue;
+        }
+        const parsed = parseVersionedId(funcId);
+        const functionKey = parsed.baseName;
+        const version = parsed.version ?? meta.version ?? 1;
+        result.set(funcId, {
+            functionKey,
+            version,
+            contractHash: meta.contractHash,
+        });
+    }
+    return result;
+}

package/dist/utils/custom-types-generator.d.ts

@@ -0,0 +1,9 @@
+import { TypesMap } from '../types-map.js';
+/**
+ * NOTE: Code generation normally belongs in @pikku/cli, not the inspector.
+ * This is here because the schema generator needs the custom types content
+ * as a virtual TypeScript source file (in-memory, no disk write) so that
+ * ts-json-schema-generator can discover inline/custom types from typesMap.
+ */
+export declare function sanitizeTypeName(name: string): string;
+export declare function generateCustomTypes(typesMap: TypesMap, requiredTypes: Set<string>): string;

package/dist/utils/custom-types-generator.js

@@ -0,0 +1,71 @@
+/**
+ * NOTE: Code generation normally belongs in @pikku/cli, not the inspector.
+ * This is here because the schema generator needs the custom types content
+ * as a virtual TypeScript source file (in-memory, no disk write) so that
+ * ts-json-schema-generator can discover inline/custom types from typesMap.
+ */
+export function sanitizeTypeName(name) {
+    return name.replace(/[^a-zA-Z0-9_$]/g, '_');
+}
+export function generateCustomTypes(typesMap, requiredTypes) {
+    const typeDeclarations = Array.from(typesMap.customTypes.entries())
+        .filter(([_name, { type }]) => {
+        const hasUndefinedGeneric = /\b(Name|In|Out|Key)\b/.test(type) && /\[.*\]/.test(type);
+        return !hasUndefinedGeneric;
+    })
+        .map(([originalName, { type, references }]) => {
+        const name = sanitizeTypeName(originalName);
+        references.forEach((refName) => {
+            if (refName !== '__object' && !refName.startsWith('__object_')) {
+                requiredTypes.add(refName);
+            }
+        });
+        const typeString = type;
+        const typeNameRegex = /\b[A-Z][a-zA-Z0-9]*\b/g;
+        const potentialTypes = typeString.match(typeNameRegex) || [];
+        potentialTypes.forEach((typeName) => {
+            if (typeString.includes(`"${typeName}"`) ||
+                [
+                    'Pick',
+                    'Omit',
+                    'Partial',
+                    'Required',
+                    'Record',
+                    'Readonly',
+                ].includes(typeName)) {
+                return;
+            }
+            try {
+                const typeMeta = typesMap.getTypeMeta(typeName);
+                if (typeMeta.path) {
+                    requiredTypes.add(typeMeta.originalName);
+                }
+            }
+            catch {
+                // Type not found in map (ambient/builtin type)
+            }
+        });
+        if (name === type)
+            return null;
+        return `export type ${name} = ${type}`;
+    });
+    const importsByPath = new Map();
+    for (const typeName of requiredTypes) {
+        try {
+            const typeMeta = typesMap.getTypeMeta(typeName);
+            if (typeMeta.path) {
+                if (!importsByPath.has(typeMeta.path)) {
+                    importsByPath.set(typeMeta.path, new Set());
+                }
+                importsByPath.get(typeMeta.path).add(typeMeta.originalName);
+            }
+        }
+        catch {
+            // Type not found in map
+        }
+    }
+    const importLines = Array.from(importsByPath.entries())
+        .map(([path, types]) => `import type { ${Array.from(types).join(', ')} } from '${path}'`)
+        .join('\n');
+    return `${importLines}\n\n${typeDeclarations.filter(Boolean).join('\n')}`;
+}

package/dist/utils/detect-schema-vendor.d.ts

@@ -0,0 +1,22 @@
+import * as ts from 'typescript';
+import type { SchemaVendor, InspectorLogger } from '../types.js';
+/**
+ * Detect the schema vendor by tracing the type back to its library origin.
+ * This handles locally-defined schemas like `export const MySchema = z.object({...})`
+ * by checking where the type itself originates from.
+ *
+ * Supports multiple schema libraries in the same project (e.g., during migration
+ * from one library to another).
+ */
+export declare const detectSchemaVendor: (identifier: ts.Identifier, checker: ts.TypeChecker) => SchemaVendor;
+/**
+ * Detect schema vendor and log a fatal error if unknown.
+ * Returns the vendor if successful, or undefined if unknown (after logging error).
+ *
+ * @param identifier - The TypeScript identifier for the schema variable
+ * @param checker - TypeScript type checker
+ * @param logger - Inspector logger for error reporting
+ * @param context - Description of what the schema is for (e.g., "Credential 'myCredential'")
+ * @param sourceFile - Source file path for error message
+ */
+export declare const detectSchemaVendorOrError: (identifier: ts.Identifier, checker: ts.TypeChecker, logger: InspectorLogger, context: string, sourceFile: string) => Exclude<SchemaVendor, "unknown"> | undefined;

package/dist/utils/detect-schema-vendor.js

@@ -0,0 +1,76 @@
+import { ErrorCode } from '../error-codes.js';
+/**
+ * Detect the schema vendor by tracing the type back to its library origin.
+ * This handles locally-defined schemas like `export const MySchema = z.object({...})`
+ * by checking where the type itself originates from.
+ *
+ * Supports multiple schema libraries in the same project (e.g., during migration
+ * from one library to another).
+ */
+export const detectSchemaVendor = (identifier, checker) => {
+    const type = checker.getTypeAtLocation(identifier);
+    if (!type)
+        return 'unknown';
+    // Check the type's symbol declarations to find the library origin
+    const checkTypeOrigin = (t) => {
+        const symbol = t.getSymbol() || t.aliasSymbol;
+        if (symbol) {
+            const decls = symbol.getDeclarations();
+            if (decls) {
+                for (const decl of decls) {
+                    const fileName = decl.getSourceFile().fileName;
+                    if (fileName.includes('node_modules/zod'))
+                        return 'zod';
+                    if (fileName.includes('node_modules/valibot'))
+                        return 'valibot';
+                    if (fileName.includes('node_modules/arktype'))
+                        return 'arktype';
+                    if (fileName.includes('node_modules/@effect/schema'))
+                        return 'effect';
+                }
+            }
+        }
+        // Check base types for class/interface hierarchies
+        const baseTypes = t.getBaseTypes?.();
+        if (baseTypes) {
+            for (const baseType of baseTypes) {
+                const result = checkTypeOrigin(baseType);
+                if (result)
+                    return result;
+            }
+        }
+        return null;
+    };
+    const vendor = checkTypeOrigin(type);
+    if (vendor)
+        return vendor;
+    // Fallback: check type arguments (for generic types like z.ZodObject<...>)
+    if (type.typeArguments) {
+        for (const arg of type.typeArguments || []) {
+            const result = checkTypeOrigin(arg);
+            if (result)
+                return result;
+        }
+    }
+    return 'unknown';
+};
+/**
+ * Detect schema vendor and log a fatal error if unknown.
+ * Returns the vendor if successful, or undefined if unknown (after logging error).
+ *
+ * @param identifier - The TypeScript identifier for the schema variable
+ * @param checker - TypeScript type checker
+ * @param logger - Inspector logger for error reporting
+ * @param context - Description of what the schema is for (e.g., "Credential 'myCredential'")
+ * @param sourceFile - Source file path for error message
+ */
+export const detectSchemaVendorOrError = (identifier, checker, logger, context, sourceFile) => {
+    const vendor = detectSchemaVendor(identifier, checker);
+    if (vendor === 'unknown') {
+        logger.critical(ErrorCode.INLINE_SCHEMA, `${context} schema vendor could not be determined from '${sourceFile}'. ` +
+            `Supported vendors: zod, valibot, arktype, @effect/schema. ` +
+            `Ensure your schema is imported from a supported validation library.`);
+        return undefined;
+    }
+    return vendor;
+};

package/dist/utils/ensure-function-metadata.d.ts

@@ -1,6 +1,9 @@
+import * as ts from 'typescript';
 import { InspectorState } from '../types.js';
 /**
- * Ensures that function metadata exists for a given pikkuFuncName.
+ * Ensures that function metadata exists for a given pikkuFuncId.
  * Creates stub metadata if it doesn't exist (useful for inline functions).
+ * When funcInitializer and checker are provided, resolves types and
+ * extracts tags/middleware/permissions from the pikkuFunc() config.
  */
-export declare function ensureFunctionMetadata(state: InspectorState, pikkuFuncName: string, fallbackName?: string): void;
+export declare function ensureFunctionMetadata(state: InspectorState, pikkuFuncId: string, fallbackName?: string, funcInitializer?: ts.Node, checker?: ts.TypeChecker, isHelper?: boolean): void;