@pikku/inspector 0.12.106 → 0.12.108

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/dist/add/add-auth.d.ts +1 -9
  2. package/dist/add/add-auth.js +64 -17
  3. package/dist/add/add-cli.js +4 -0
  4. package/dist/add/add-functions.js +27 -31
  5. package/dist/add/add-keyed-wiring.js +22 -2
  6. package/dist/add/add-middleware.js +17 -16
  7. package/dist/add/add-permission.d.ts +0 -3
  8. package/dist/add/add-permission.js +213 -22
  9. package/dist/add/add-scope.d.ts +1 -7
  10. package/dist/add/add-scope.js +1 -21
  11. package/dist/add/check-indirect-registrations.d.ts +9 -0
  12. package/dist/add/check-indirect-registrations.js +114 -0
  13. package/dist/error-codes.d.ts +1 -0
  14. package/dist/error-codes.js +1 -0
  15. package/dist/finalize.d.ts +10 -0
  16. package/dist/finalize.js +102 -0
  17. package/dist/index.d.ts +8 -6
  18. package/dist/index.js +6 -5
  19. package/dist/initial-state.d.ts +7 -0
  20. package/dist/initial-state.js +216 -0
  21. package/dist/inspector.d.ts +6 -4
  22. package/dist/inspector.js +28 -302
  23. package/dist/lite.d.ts +26 -0
  24. package/dist/lite.js +25 -0
  25. package/dist/source-file-cache.d.ts +11 -0
  26. package/dist/source-file-cache.js +34 -10
  27. package/dist/types-map.js +2 -1
  28. package/dist/types.d.ts +32 -0
  29. package/dist/utils/apply-declared-scopes.d.ts +8 -0
  30. package/dist/utils/apply-declared-scopes.js +21 -0
  31. package/dist/utils/canonical-type-string.d.ts +14 -0
  32. package/dist/utils/canonical-type-string.js +162 -0
  33. package/dist/utils/context-based-id.d.ts +7 -0
  34. package/dist/utils/context-based-id.js +9 -0
  35. package/dist/utils/custom-types-generator.d.ts +15 -1
  36. package/dist/utils/custom-types-generator.js +17 -5
  37. package/dist/utils/ensure-function-metadata.d.ts +0 -14
  38. package/dist/utils/ensure-function-metadata.js +4 -1
  39. package/dist/utils/extract-function-name.d.ts +1 -1
  40. package/dist/utils/extract-function-name.js +1 -3
  41. package/dist/utils/filter-inspector-state.js +31 -1
  42. package/dist/utils/get-property-value.d.ts +5 -0
  43. package/dist/utils/get-property-value.js +14 -0
  44. package/dist/utils/inspector-constants.d.ts +16 -0
  45. package/dist/utils/inspector-constants.js +16 -0
  46. package/dist/utils/post-process.d.ts +1 -2
  47. package/dist/utils/post-process.js +27 -27
  48. package/dist/utils/read-jsx-literal-text.js +31 -1
  49. package/dist/utils/resolve-callee-name.d.ts +27 -0
  50. package/dist/utils/resolve-callee-name.js +147 -0
  51. package/dist/utils/resolve-service-types.d.ts +8 -0
  52. package/dist/utils/resolve-service-types.js +21 -0
  53. package/dist/utils/schema-generator.js +29 -2
  54. package/dist/utils/serialize-inspector-state.d.ts +7 -1
  55. package/dist/utils/serialize-inspector-state.js +16 -1
  56. package/dist/utils/workflow/dsl/patterns.d.ts +1 -8
  57. package/dist/utils/workflow/dsl/patterns.js +1 -7
  58. package/dist/visit.js +2 -0
  59. package/package.json +25 -9
  60. package/CHANGELOG.md +0 -4368
  61. package/OPTIMIZATION-PLAN.md +0 -201
  62. package/knowledge/decisions/a-channel-with-auth-false-marks-its-connect-and-disconnect-sessionless.md +0 -22
  63. package/knowledge/decisions/a-declared-scope-id-never-shadows-a-definition.md +0 -20
  64. package/knowledge/decisions/a-dsl-step-virtual-user-is-the-literal-name-in-its-options.md +0 -27
  65. package/knowledge/decisions/a-feature-flags-anyof-is-read-from-the-ast-and-an-empty-list-is-refused.md +0 -20
  66. package/knowledge/decisions/a-non-literal-string-array-reads-as-absent.md +0 -25
  67. package/knowledge/decisions/a-permission-with-an-underscore-data-parameter-takes-no-data.md +0 -20
  68. package/knowledge/decisions/a-provider-login-virtual-user-is-never-runnable.md +0 -27
  69. package/knowledge/decisions/a-remote-addon-bound-credential-or-secret-must-be-wired.md +0 -27
  70. package/knowledge/decisions/a-route-auth-overrides-its-groups-auth.md +0 -22
  71. package/knowledge/decisions/a-route-requires-a-session-when-any-auth-signal-says-so.md +0 -29
  72. package/knowledge/decisions/a-webhook-source-with-verify-gets-a-singleton-secret-credential.md +0 -21
  73. package/knowledge/decisions/a-wire-with-auth-disabled-cannot-point-at-a-pikkufunc.md +0 -21
  74. package/knowledge/decisions/addon-contracts-cannot-wire-or-declare-handlers.md +0 -25
  75. package/knowledge/decisions/addon-declarations-name-the-secrets-and-credentials-the-app-lends-it.md +0 -19
  76. package/knowledge/decisions/an-inline-wiring-function-is-sessionless-unless-built-with-pikkufunc.md +0 -23
  77. package/knowledge/decisions/better-auth-admin-plugin-is-refused.md +0 -24
  78. package/knowledge/decisions/define-screens-scopes-must-be-string-literals.md +0 -18
  79. package/knowledge/decisions/index.md +0 -38
  80. package/knowledge/decisions/inspector-records-a-non-literal-global-grant-as-source-text.md +0 -20
  81. package/knowledge/decisions/only-one-pikku-better-auth-export-per-codebase.md +0 -19
  82. package/knowledge/decisions/scope-references-and-secret-aliases-are-critical-diagnostics.md +0 -23
  83. package/knowledge/decisions/scope-segments-may-not-be-wildcards-or-contain-colons.md +0 -23
  84. package/knowledge/decisions/shorthand-permission-entries-are-extracted.md +0 -22
  85. package/knowledge/decisions/system-roles-declare-literal-unqualified-scopes.md +0 -28
  86. package/knowledge/decisions/the-inspector-records-agent-permissions-only-to-aggregate-services.md +0 -14
  87. package/knowledge/decisions/vault-secrets-reach-no-sink-and-pii-stays-out-of-logs-and-webhooks.md +0 -30
  88. package/knowledge/decisions/webhook-gateway-wrappers-are-sessionless-and-gateway-auth-runs-inside-the-handler.md +0 -26
  89. package/knowledge/index.md +0 -14
  90. package/knowledge/questions/does-a-non-literal-remote-addon-auth-get-checked.md +0 -26
  91. package/knowledge/questions/index.md +0 -16
  92. package/knowledge/questions/is-an-incomplete-oauth2-block-dropped-without-a-log.md +0 -23
  93. package/knowledge/questions/should-app-functions-named-like-scenario-instrumentation-be-refused.md +0 -28
  94. package/knowledge/questions/should-the-openapi-document-default-every-operation-to-a-bearer-or-api-key.md +0 -22
  95. package/run-tests.sh +0 -68
  96. package/src/utils/test-data/inspector-state.json +0 -1687
package/dist/index.js CHANGED
@@ -1,18 +1,19 @@
1
- export { inspect, getInitialInspectorState } from './inspector.js';
1
+ export { inspect, analyzeProgram } from './inspector.js';
2
+ export { getInitialInspectorState } from './initial-state.js';
3
+ export { finalizeInspectorState } from './finalize.js';
2
4
  export { ErrorCode } from './error-codes.js';
3
- export { AUTH_HANDLER_FUNC_ID } from './add/add-auth.js';
5
+ export { AUTH_HANDLER_FUNC_ID } from './utils/inspector-constants.js';
4
6
  export { SCENARIO_INSTRUMENTATION_FUNCTIONS, isScenarioInstrumentationFunction, } from './add/scenario-instrumentation.js';
5
7
  export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
6
8
  export { filterInspectorState } from './utils/filter-inspector-state.js';
7
9
  export { incompatibleServicesFor, resolveDeployTarget, } from './utils/resolve-deploy-target.js';
8
- export { generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
10
+ export { generateCustomTypes, customTypeNames, sanitizeTypeName, } from './utils/custom-types-generator.js';
9
11
  export { unresolvedSchemaReferences } from './utils/post-process.js';
10
12
  export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
11
13
  export { serializeMCPJson } from './utils/serialize-mcp-json.js';
12
- export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/index.js';
14
+ export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/deserialize-dsl-workflow.js';
13
15
  export { getFilesAndMethods } from './utils/get-files-and-methods.js';
14
16
  export { resolveFunctionMeta } from './utils/resolve-function-meta.js';
15
- export { resolveCoreType } from './utils/resolve-core-type.js';
16
17
  export { readModuleSpecifiers } from './utils/read-module-specifiers.js';
17
18
  export { readJsxLiteralText } from './utils/read-jsx-literal-text.js';
18
19
  export { readTsconfigOutDir } from './utils/read-tsconfig-out-dir.js';
@@ -0,0 +1,7 @@
1
+ import type { InspectorState } from './types.js';
2
+ /**
3
+ * Creates an initial/empty inspector state with all required properties initialized
4
+ * @param rootDir - The root directory for the project
5
+ * @returns A fresh InspectorState with empty collections
6
+ */
7
+ export declare function getInitialInspectorState(rootDir: string): InspectorState;
@@ -0,0 +1,216 @@
1
+ import { TypesMap } from './types-map.js';
2
+ /**
3
+ * Creates an initial/empty inspector state with all required properties initialized
4
+ * @param rootDir - The root directory for the project
5
+ * @returns A fresh InspectorState with empty collections
6
+ */
7
+ export function getInitialInspectorState(rootDir) {
8
+ return {
9
+ rootDir,
10
+ singletonServicesTypeImportMap: new Map(),
11
+ wireServicesTypeImportMap: new Map(),
12
+ userSessionTypeImportMap: new Map(),
13
+ configTypeImportMap: new Map(),
14
+ singletonServicesFactories: new Map(),
15
+ wireServicesFactories: new Map(),
16
+ wireServicesMeta: new Map(),
17
+ addonRequiredParentServices: [],
18
+ addonCreatedServices: [],
19
+ addonServicesFactorySeen: false,
20
+ addonServerlessIncompatible: new Map(),
21
+ configFactories: new Map(),
22
+ serverLifecycleFactories: new Map(),
23
+ filesAndMethods: {},
24
+ filesAndMethodsErrors: new Map(),
25
+ typesLookup: new Map(),
26
+ schemaLookup: new Map(),
27
+ schemas: {},
28
+ functions: {
29
+ typesMap: new TypesMap(),
30
+ meta: {},
31
+ files: new Map(),
32
+ approvalDescriptions: {},
33
+ dynamicImportIds: new Set(),
34
+ },
35
+ http: {
36
+ metaInputTypes: new Map(),
37
+ meta: {
38
+ get: {},
39
+ post: {},
40
+ put: {},
41
+ delete: {},
42
+ head: {},
43
+ patch: {},
44
+ options: {},
45
+ },
46
+ files: new Set(),
47
+ routeMiddleware: new Map(),
48
+ },
49
+ channels: {
50
+ files: new Set(),
51
+ meta: {},
52
+ },
53
+ gateways: {
54
+ meta: {},
55
+ files: new Set(),
56
+ },
57
+ triggers: {
58
+ meta: {},
59
+ sourceMeta: {},
60
+ webhookSourceMeta: {},
61
+ files: new Set(),
62
+ },
63
+ scheduledTasks: {
64
+ meta: {},
65
+ files: new Set(),
66
+ },
67
+ queueWorkers: {
68
+ meta: {},
69
+ files: new Set(),
70
+ },
71
+ workflows: {
72
+ meta: {},
73
+ files: new Map(),
74
+ graphMeta: {},
75
+ graphFiles: new Map(),
76
+ featureFiles: new Map(),
77
+ invokedWorkflows: new Set(),
78
+ },
79
+ rpc: {
80
+ internalMeta: {},
81
+ internalFiles: new Map(),
82
+ exposedMeta: {},
83
+ exposedFiles: new Map(),
84
+ remoteMeta: {},
85
+ remoteFiles: new Map(),
86
+ invokedFunctions: new Set(),
87
+ invokedFunctionsByFile: new Map(),
88
+ usedAddons: new Set(),
89
+ wireAddonDeclarations: new Map(),
90
+ wireAddonFiles: new Set(),
91
+ },
92
+ mcpEndpoints: {
93
+ resourcesMeta: {},
94
+ toolsMeta: {},
95
+ promptsMeta: {},
96
+ files: new Set(),
97
+ surfaces: {},
98
+ },
99
+ agents: {
100
+ agentsMeta: {},
101
+ files: new Map(),
102
+ invokedAgentsByFile: new Map(),
103
+ },
104
+ scorers: {
105
+ scorersMeta: {},
106
+ files: new Map(),
107
+ },
108
+ cli: {
109
+ meta: {
110
+ programs: {},
111
+ renderers: {},
112
+ },
113
+ files: new Set(),
114
+ },
115
+ nodes: {
116
+ meta: {},
117
+ files: new Set(),
118
+ },
119
+ auth: {
120
+ providers: [],
121
+ plugins: [],
122
+ files: new Set(),
123
+ definition: null,
124
+ },
125
+ secrets: {
126
+ definitions: [],
127
+ files: new Set(),
128
+ usage: new Map(),
129
+ },
130
+ surfaceUsage: {},
131
+ credentials: {
132
+ definitions: [],
133
+ files: new Set(),
134
+ },
135
+ scopes: {
136
+ definitions: [],
137
+ files: new Set(),
138
+ },
139
+ systemRoles: {
140
+ definitions: [],
141
+ files: new Set(),
142
+ },
143
+ featureFlags: {
144
+ definitions: [],
145
+ files: new Set(),
146
+ },
147
+ virtualUsers: {
148
+ definitions: [],
149
+ files: new Set(),
150
+ },
151
+ variables: {
152
+ definitions: [],
153
+ files: new Set(),
154
+ },
155
+ manifest: {
156
+ initial: null,
157
+ current: null,
158
+ errors: [],
159
+ },
160
+ middleware: {
161
+ definitions: {},
162
+ instances: {},
163
+ tagMiddleware: new Map(),
164
+ globalFiles: new Set(),
165
+ },
166
+ channelMiddleware: {
167
+ definitions: {},
168
+ instances: {},
169
+ tagMiddleware: new Map(),
170
+ },
171
+ agentMiddleware: {
172
+ definitions: {},
173
+ },
174
+ permissions: {
175
+ definitions: {},
176
+ instances: {},
177
+ global: [],
178
+ },
179
+ serviceAggregation: {
180
+ requiredServices: new Set(),
181
+ usedFunctions: new Set(),
182
+ usedMiddleware: new Set(),
183
+ usedPermissions: new Set(),
184
+ allSingletonServices: [],
185
+ allWireServices: [],
186
+ },
187
+ resolvedIOTypes: {},
188
+ middlewareGroupsMeta: {
189
+ definitions: {},
190
+ instances: {},
191
+ httpGroups: {},
192
+ tagGroups: {},
193
+ channelMiddleware: {
194
+ definitions: {},
195
+ instances: {},
196
+ tagGroups: {},
197
+ },
198
+ },
199
+ permissionsGroupsMeta: {
200
+ definitions: {},
201
+ },
202
+ requiredSchemas: new Set(),
203
+ openAPISpec: null,
204
+ diagnostics: [],
205
+ addonFunctions: {},
206
+ exportedContracts: {
207
+ http: {},
208
+ cli: {},
209
+ channel: {},
210
+ addonHttp: {},
211
+ addonCli: {},
212
+ addonChannel: {},
213
+ },
214
+ program: null,
215
+ };
216
+ }
@@ -1,8 +1,10 @@
1
1
  import type { InspectorState, InspectorLogger, InspectorOptions } from './types.js';
2
+ import { getInitialInspectorState } from './initial-state.js';
3
+ export { getInitialInspectorState };
2
4
  /**
3
- * Creates an initial/empty inspector state with all required properties initialized
4
- * @param rootDir - The root directory for the project
5
- * @returns A fresh InspectorState with empty collections
5
+ * The engine-specific half of an inspection: builds the program, walks it with
6
+ * the checker and generates the schemas. What it returns is the pre-finalize
7
+ * state that `finalizeInspectorState` completes.
6
8
  */
7
- export declare function getInitialInspectorState(rootDir: string): InspectorState;
9
+ export declare const analyzeProgram: (logger: InspectorLogger, routeFiles: string[], options?: InspectorOptions) => Promise<InspectorState>;
8
10
  export declare const inspect: (logger: InspectorLogger, routeFiles: string[], options?: InspectorOptions) => Promise<InspectorState>;
package/dist/inspector.js CHANGED
@@ -1,244 +1,21 @@
1
1
  import * as ts from 'typescript';
2
- import { applyDeclaredScopes } from './add/add-scope.js';
3
2
  import { performance } from 'perf_hooks';
4
3
  import { dirname, relative, resolve } from 'path';
5
4
  import { visitSetup, visitFunctions, visitRoutes } from './visit.js';
6
- import { TypesMap } from './types-map.js';
7
- import { getFilesAndMethods } from './utils/get-files-and-methods.js';
8
5
  import { findCommonAncestor } from './utils/find-root-dir.js';
9
6
  import { createSourceFileCacheHost } from './source-file-cache.js';
10
7
  import { createNestedProjectFilter } from './utils/nested-project-filter.js';
11
8
  import { toProgramPath } from './utils/program-path.js';
12
- import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateAgentScorerReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateAddonUses, validateAddonContentGrants, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validateVirtualUserRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, validateNoSecretAliasServices, registerDerivedOAuth2AppSecrets, validateSecretUsage, computeDiagnostics, validateSchemaReferences, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateScenarioFeatures, validateWorkflowGraphAddons, } from './utils/post-process.js';
13
- import { validateExposedFunctionsGated } from './utils/validate-exposed-functions-gated.js';
14
- import { validateTagsResolveToMiddleware } from './utils/validate-tags-resolve-to-middleware.js';
15
- import { validateSingleStepWorkflows } from './utils/validate-single-step-workflows.js';
16
- import { annotateHttpRouteAuth } from './utils/annotate-http-route-auth.js';
17
- import { generateOpenAPISpec } from './utils/serialize-openapi-json.js';
18
- import { pikkuState } from '@pikku/core/state';
19
9
  import { resolveLatestVersions } from './utils/resolve-versions.js';
20
10
  import { validateWebhookSourceTriggers } from './add/add-trigger.js';
21
- import { finalizeWorkflows } from './utils/workflow/graph/finalize-workflows.js';
22
- import { finalizeWorkflowHelperTypes, finalizeWorkflowWires, } from './utils/workflow/graph/finalize-workflow-wires.js';
23
11
  import { generateAllSchemas } from './utils/schema-generator.js';
24
12
  import { extractSecretUsage } from './utils/extract-secret-usage.js';
25
13
  import { accumulateSurfaceUsage, surfaceUsageArea, } from './utils/extract-surface-usage.js';
26
- import { loadAddonFunctionsMeta, loadAddonSchemas, } from './utils/load-addon-functions-meta.js';
27
- import { computeContractHashes, extractContractsFromMeta, updateManifest, createEmptyManifest, validateContracts, } from './utils/contract-hashes.js';
28
- /**
29
- * Creates an initial/empty inspector state with all required properties initialized
30
- * @param rootDir - The root directory for the project
31
- * @returns A fresh InspectorState with empty collections
32
- */
33
- export function getInitialInspectorState(rootDir) {
34
- return {
35
- rootDir,
36
- singletonServicesTypeImportMap: new Map(),
37
- wireServicesTypeImportMap: new Map(),
38
- userSessionTypeImportMap: new Map(),
39
- configTypeImportMap: new Map(),
40
- singletonServicesFactories: new Map(),
41
- wireServicesFactories: new Map(),
42
- wireServicesMeta: new Map(),
43
- addonRequiredParentServices: [],
44
- addonCreatedServices: [],
45
- addonServicesFactorySeen: false,
46
- addonServerlessIncompatible: new Map(),
47
- configFactories: new Map(),
48
- serverLifecycleFactories: new Map(),
49
- filesAndMethods: {},
50
- filesAndMethodsErrors: new Map(),
51
- typesLookup: new Map(),
52
- schemaLookup: new Map(),
53
- schemas: {},
54
- functions: {
55
- typesMap: new TypesMap(),
56
- meta: {},
57
- files: new Map(),
58
- approvalDescriptions: {},
59
- dynamicImportIds: new Set(),
60
- },
61
- http: {
62
- metaInputTypes: new Map(),
63
- meta: {
64
- get: {},
65
- post: {},
66
- put: {},
67
- delete: {},
68
- head: {},
69
- patch: {},
70
- options: {},
71
- },
72
- files: new Set(),
73
- routeMiddleware: new Map(),
74
- },
75
- channels: {
76
- files: new Set(),
77
- meta: {},
78
- },
79
- gateways: {
80
- meta: {},
81
- files: new Set(),
82
- },
83
- triggers: {
84
- meta: {},
85
- sourceMeta: {},
86
- webhookSourceMeta: {},
87
- files: new Set(),
88
- },
89
- scheduledTasks: {
90
- meta: {},
91
- files: new Set(),
92
- },
93
- queueWorkers: {
94
- meta: {},
95
- files: new Set(),
96
- },
97
- workflows: {
98
- meta: {},
99
- files: new Map(),
100
- graphMeta: {},
101
- graphFiles: new Map(),
102
- featureFiles: new Map(),
103
- invokedWorkflows: new Set(),
104
- },
105
- rpc: {
106
- internalMeta: {},
107
- internalFiles: new Map(),
108
- exposedMeta: {},
109
- exposedFiles: new Map(),
110
- remoteMeta: {},
111
- remoteFiles: new Map(),
112
- invokedFunctions: new Set(),
113
- invokedFunctionsByFile: new Map(),
114
- usedAddons: new Set(),
115
- wireAddonDeclarations: new Map(),
116
- wireAddonFiles: new Set(),
117
- },
118
- mcpEndpoints: {
119
- resourcesMeta: {},
120
- toolsMeta: {},
121
- promptsMeta: {},
122
- files: new Set(),
123
- surfaces: {},
124
- },
125
- agents: {
126
- agentsMeta: {},
127
- files: new Map(),
128
- invokedAgentsByFile: new Map(),
129
- },
130
- scorers: {
131
- scorersMeta: {},
132
- files: new Map(),
133
- },
134
- cli: {
135
- meta: {
136
- programs: {},
137
- renderers: {},
138
- },
139
- files: new Set(),
140
- },
141
- nodes: {
142
- meta: {},
143
- files: new Set(),
144
- },
145
- auth: {
146
- providers: [],
147
- plugins: [],
148
- files: new Set(),
149
- definition: null,
150
- },
151
- secrets: {
152
- definitions: [],
153
- files: new Set(),
154
- usage: new Map(),
155
- },
156
- surfaceUsage: {},
157
- credentials: {
158
- definitions: [],
159
- files: new Set(),
160
- },
161
- scopes: {
162
- definitions: [],
163
- files: new Set(),
164
- },
165
- systemRoles: {
166
- definitions: [],
167
- files: new Set(),
168
- },
169
- featureFlags: {
170
- definitions: [],
171
- files: new Set(),
172
- },
173
- virtualUsers: {
174
- definitions: [],
175
- files: new Set(),
176
- },
177
- variables: {
178
- definitions: [],
179
- files: new Set(),
180
- },
181
- manifest: {
182
- initial: null,
183
- current: null,
184
- errors: [],
185
- },
186
- middleware: {
187
- definitions: {},
188
- instances: {},
189
- tagMiddleware: new Map(),
190
- globalFiles: new Set(),
191
- },
192
- channelMiddleware: {
193
- definitions: {},
194
- instances: {},
195
- tagMiddleware: new Map(),
196
- },
197
- agentMiddleware: {
198
- definitions: {},
199
- },
200
- permissions: {
201
- definitions: {},
202
- instances: {},
203
- },
204
- serviceAggregation: {
205
- requiredServices: new Set(),
206
- usedFunctions: new Set(),
207
- usedMiddleware: new Set(),
208
- usedPermissions: new Set(),
209
- allSingletonServices: [],
210
- allWireServices: [],
211
- },
212
- resolvedIOTypes: {},
213
- middlewareGroupsMeta: {
214
- definitions: {},
215
- instances: {},
216
- httpGroups: {},
217
- tagGroups: {},
218
- channelMiddleware: {
219
- definitions: {},
220
- instances: {},
221
- tagGroups: {},
222
- },
223
- },
224
- permissionsGroupsMeta: {
225
- definitions: {},
226
- },
227
- requiredSchemas: new Set(),
228
- openAPISpec: null,
229
- diagnostics: [],
230
- addonFunctions: {},
231
- exportedContracts: {
232
- http: {},
233
- cli: {},
234
- channel: {},
235
- addonHttp: {},
236
- addonCli: {},
237
- addonChannel: {},
238
- },
239
- program: null,
240
- };
241
- }
14
+ import { loadAddonFunctionsMeta } from './utils/load-addon-functions-meta.js';
15
+ import { resolveServiceTypes } from './utils/resolve-service-types.js';
16
+ import { finalizeInspectorState } from './finalize.js';
17
+ import { getInitialInspectorState } from './initial-state.js';
18
+ export { getInitialInspectorState };
242
19
  /**
243
20
  * The path mappings the inspector's program has to share with the project.
244
21
  *
@@ -272,7 +49,12 @@ const readProjectPathMappings = (logger, tsconfig) => {
272
49
  ...(pathsBasePath !== undefined ? { pathsBasePath } : {}),
273
50
  };
274
51
  };
275
- export const inspect = async (logger, routeFiles, options = {}) => {
52
+ /**
53
+ * The engine-specific half of an inspection: builds the program, walks it with
54
+ * the checker and generates the schemas. What it returns is the pre-finalize
55
+ * state that `finalizeInspectorState` completes.
56
+ */
57
+ export const analyzeProgram = async (logger, routeFiles, options = {}) => {
276
58
  const normalizedRouteFiles = routeFiles.map((file) => resolve(file));
277
59
  const compilerOptions = {
278
60
  ...readProjectPathMappings(logger, options.tsconfig),
@@ -364,81 +146,11 @@ export const inspect = async (logger, routeFiles, options = {}) => {
364
146
  const startSchemas = performance.now();
365
147
  state.schemas = await generateAllSchemas(logger, options.schemaConfig, state);
366
148
  logger.debug(`generateAllSchemas took ${(performance.now() - startSchemas).toFixed(0)}ms`);
367
- computeContractHashes(state.schemas, state.functions.typesMap, state.functions.meta);
368
- computeRequiredSchemas(state, options);
369
- }
370
- // Re-load addon schemas (generateAllSchemas replaces state.schemas)
371
- await loadAddonSchemas(logger, state);
372
- // After the addon merge, not before: an addon supplies its own schemas here,
373
- // and checking earlier would report every one of them as unresolved.
374
- if (options.schemaConfig) {
375
- validateSchemaReferences(logger, state);
376
149
  }
377
- state.manifest.initial = options.manifest ?? null;
378
- const contracts = extractContractsFromMeta(state.functions.meta);
379
- const baseManifest = state.manifest.initial ?? createEmptyManifest();
380
- state.manifest.current = updateManifest(baseManifest, contracts);
381
- state.manifest.errors = validateContracts(baseManifest, contracts).errors;
382
- finalizeWorkflows(state);
383
- finalizeWorkflowHelperTypes(state);
384
- finalizeWorkflowWires(state);
385
- }
386
- // Populate filesAndMethods
387
- const startFilesAndMethods = performance.now();
388
- const { result, errors } = getFilesAndMethods(state, options.types);
389
- state.filesAndMethods = result;
390
- state.filesAndMethodsErrors = errors;
391
- logger.debug(`Get files and methods completed in ${(performance.now() - startFilesAndMethods).toFixed(2)}ms`);
392
- if (!options.setupOnly) {
393
- // Everything below re-derives from the state this pass just built, so it
394
- // supersedes whatever an earlier pass concluded about a source graph the
395
- // run has since finished generating into.
396
- logger.beginValidationPass?.();
397
- const startAggregate = performance.now();
398
- // Apply the inspected auth handler service set before aggregation so it
399
- // flows into requiredServices (the generated handler's own func is opaque).
400
- stampAuthHandlerServices(state);
401
- aggregateRequiredServices(state);
402
- logger.debug(`Aggregate required services completed in ${(performance.now() - startAggregate).toFixed(2)}ms`);
403
- computeResolvedIOTypes(state);
404
- computeMiddlewareGroupsMeta(state);
405
- computePermissionsGroupsMeta(state);
406
- validateNoSecretAliasServices(logger, checker, state);
407
- registerDerivedOAuth2AppSecrets(state);
408
- validateSecretUsage(logger, state);
409
- computeDiagnostics(state);
410
- validateSchemaWiringSeparation(logger, state);
411
- validateWorkflowGraphAddons(logger, state);
412
- validateSingleStepWorkflows(logger, state);
413
- validateScenarioServices(logger, state);
414
- validateScenarioSteps(logger, state);
415
- validateScenarioFeatures(logger, state);
416
- // Needs every route, every function and every wireAddon declaration
417
- // together, so it can only run once the whole program is inspected.
418
- annotateHttpRouteAuth(state);
419
- // Last of the validators: they read function meta and every wireAddon
420
- // declaration together, so they need the whole program inspected.
421
- validateExposedFunctionsGated(logger, state);
422
- validateTagsResolveToMiddleware(logger, state);
423
- if (options.openAPI) {
424
- state.openAPISpec = await generateOpenAPISpec(logger, state.functions.meta, state.http.meta, state.schemas, options.openAPI.additionalInfo, pikkuState(null, 'misc', 'errors'));
425
- }
426
- validateAgentModels(logger, state, options.modelAliases);
427
- validateAgentToolReferences(logger, state, options);
428
- validateAgentScorerReferences(logger, state);
429
- validateSecretOverrides(logger, state);
430
- validateVariableOverrides(logger, state);
431
- validateCredentialOverrides(logger, state);
432
- validateAddonUses(logger, state);
433
- validateAddonContentGrants(logger, state);
434
- validateRemoteAddonDependencies(logger, state);
435
- validateRemoteAddonAuth(logger, state);
436
- applyDeclaredScopes(state);
437
- validateScopeReferences(logger, state);
438
- validateSystemRoleScopes(logger, state);
439
- validateVirtualUserRoles(logger, state);
440
- logger.endValidationPass?.();
441
150
  }
151
+ // On a setup-only pass too: the CLI reads the singleton service names off
152
+ // a setup-only state to decide whether workflows have a workflowService.
153
+ state.serviceTypes = resolveServiceTypes(state, checker);
442
154
  const cpu = process.cpuUsage(cpuStart);
443
155
  state.stats = {
444
156
  files: program.getSourceFiles().length,
@@ -454,3 +166,17 @@ export const inspect = async (logger, routeFiles, options = {}) => {
454
166
  state.program = program;
455
167
  return state;
456
168
  };
169
+ export const inspect = async (logger, routeFiles, options = {}) => {
170
+ const cpuStart = process.cpuUsage();
171
+ const start = performance.now();
172
+ const state = await analyzeProgram(logger, routeFiles, options);
173
+ await finalizeInspectorState(logger, state, options);
174
+ const cpu = process.cpuUsage(cpuStart);
175
+ state.stats = {
176
+ ...state.stats,
177
+ cpuMs: Math.round((cpu.user + cpu.system) / 1000),
178
+ wallMs: Math.round(performance.now() - start),
179
+ heapUsedMb: Math.round(process.memoryUsage().heapUsed / 1048576),
180
+ };
181
+ return state;
182
+ };
package/dist/lite.d.ts ADDED
@@ -0,0 +1,26 @@
1
+ /**
2
+ * The inspector's exports that never load the TypeScript compiler.
3
+ *
4
+ * `@pikku/inspector` itself pulls in `typescript` and `ts-json-schema-generator`
5
+ * at module load, which costs a CLI command that only wants an error code or a
6
+ * serializer most of its startup time, and costs the native engine the
7
+ * compiler's memory for nothing. Everything a consumer of an `InspectorState`
8
+ * needs is here and safe to import eagerly; `lite.test.ts` fails if anything
9
+ * reachable from this file imports `typescript`.
10
+ */
11
+ export { getInitialInspectorState } from './initial-state.js';
12
+ export { ErrorCode } from './error-codes.js';
13
+ export type { DiagnosticSeverity, CodedDiagnostic } from './error-codes.js';
14
+ export { AUTH_HANDLER_FUNC_ID } from './utils/inspector-constants.js';
15
+ export { SCENARIO_INSTRUMENTATION_FUNCTIONS, isScenarioInstrumentationFunction, } from './add/scenario-instrumentation.js';
16
+ export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
17
+ export { filterInspectorState } from './utils/filter-inspector-state.js';
18
+ export { incompatibleServicesFor, resolveDeployTarget, } from './utils/resolve-deploy-target.js';
19
+ export { customTypeNames, generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
20
+ export { unresolvedSchemaReferences } from './utils/post-process.js';
21
+ export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
22
+ export { serializeMCPJson } from './utils/serialize-mcp-json.js';
23
+ export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/deserialize-dsl-workflow.js';
24
+ export { resolveFunctionMeta } from './utils/resolve-function-meta.js';
25
+ export { resolveCoreType } from './utils/resolve-core-type.js';
26
+ export { addonResolutionDirs, createAddonResolver, } from './utils/addon-resolution.js';
package/dist/lite.js ADDED
@@ -0,0 +1,25 @@
1
+ /**
2
+ * The inspector's exports that never load the TypeScript compiler.
3
+ *
4
+ * `@pikku/inspector` itself pulls in `typescript` and `ts-json-schema-generator`
5
+ * at module load, which costs a CLI command that only wants an error code or a
6
+ * serializer most of its startup time, and costs the native engine the
7
+ * compiler's memory for nothing. Everything a consumer of an `InspectorState`
8
+ * needs is here and safe to import eagerly; `lite.test.ts` fails if anything
9
+ * reachable from this file imports `typescript`.
10
+ */
11
+ export { getInitialInspectorState } from './initial-state.js';
12
+ export { ErrorCode } from './error-codes.js';
13
+ export { AUTH_HANDLER_FUNC_ID } from './utils/inspector-constants.js';
14
+ export { SCENARIO_INSTRUMENTATION_FUNCTIONS, isScenarioInstrumentationFunction, } from './add/scenario-instrumentation.js';
15
+ export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
16
+ export { filterInspectorState } from './utils/filter-inspector-state.js';
17
+ export { incompatibleServicesFor, resolveDeployTarget, } from './utils/resolve-deploy-target.js';
18
+ export { customTypeNames, generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
19
+ export { unresolvedSchemaReferences } from './utils/post-process.js';
20
+ export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
21
+ export { serializeMCPJson } from './utils/serialize-mcp-json.js';
22
+ export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/deserialize-dsl-workflow.js';
23
+ export { resolveFunctionMeta } from './utils/resolve-function-meta.js';
24
+ export { resolveCoreType } from './utils/resolve-core-type.js';
25
+ export { addonResolutionDirs, createAddonResolver, } from './utils/addon-resolution.js';