@pikku/inspector 0.12.14 → 0.12.17

package/src/add/pii-check.test.ts

@@ -46,30 +46,35 @@ async function runInspect(sourceCode: string) {
   return criticals
 }
 
-// ── findPiiPaths unit tests via full inspect() round-trip ────────────────────
+// ── classification semantics:
+//   secret  → never returned by any function (sessioned or not)
+//   private → only blocked in sessionless functions (pikkuSessionlessFunc)
+//   public  → safe for sessionless functions
 
 describe('PII output check — PKU910', () => {
-  test('flags a top-level Private<string> field', async () => {
+  // ── Secret<T>: always blocked ──────────────────────────────────────────────
+
+  test('flags a top-level Secret<string> field in a sessioned function', async () => {
     const criticals = await runInspect(`
 ${BRAND_TYPES}
 import { pikkuFunc } from '@pikku/core'
-export const getUser = pikkuFunc({
+export const getToken = pikkuFunc({
   func: async () => {
-    const email = 'test@example.com' as Private<string>
-    return { id: 1, email }
+    const token = 'abc' as Secret<string>
+    return { token }
   }
 })
 `)
     const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
-    assert.ok(hit, `Expected PKU910 but got: ${JSON.stringify(criticals)}`)
-    assert.match(hit.message, /email/)
+    assert.ok(hit)
+    assert.match(hit.message, /token/)
   })
 
-  test('flags a top-level Secret<string> field', async () => {
+  test('flags a top-level Secret<string> field in a sessionless function', async () => {
     const criticals = await runInspect(`
 ${BRAND_TYPES}
-import { pikkuFunc } from '@pikku/core'
-export const getToken = pikkuFunc({
+import { pikkuSessionlessFunc } from '@pikku/core'
+export const getToken = pikkuSessionlessFunc({
   func: async () => {
     const token = 'abc' as Secret<string>
     return { token }
@@ -81,11 +86,48 @@ export const getToken = pikkuFunc({
     assert.match(hit.message, /token/)
   })
 
-  test('flags a nested Private field', async () => {
+  // ── Private<T>: only blocked in sessionless functions ─────────────────────
+
+  test('flags a top-level Private<string> field in a sessionless function', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuSessionlessFunc } from '@pikku/core'
+export const getUser = pikkuSessionlessFunc({
+  func: async () => {
+    const email = 'test@example.com' as Private<string>
+    return { id: 1, email }
+  }
+})
+`)
+    const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.ok(hit, `Expected PKU910 but got: ${JSON.stringify(criticals)}`)
+    assert.match(hit.message, /email/)
+  })
+
+  test('does not flag a Private<string> field in a sessioned function', async () => {
     const criticals = await runInspect(`
 ${BRAND_TYPES}
 import { pikkuFunc } from '@pikku/core'
-export const getProfile = pikkuFunc({
+export const getUser = pikkuFunc({
+  func: async () => {
+    const email = 'test@example.com' as Private<string>
+    return { id: 1, email }
+  }
+})
+`)
+    const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.equal(
+      hit,
+      undefined,
+      `Expected no PKU910 (sessioned function may return Private fields) but got: ${JSON.stringify(hit)}`
+    )
+  })
+
+  test('flags a nested Private field in a sessionless function', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuSessionlessFunc } from '@pikku/core'
+export const getProfile = pikkuSessionlessFunc({
   func: async () => {
     const email = 'x@y.com' as Private<string>
     return { user: { id: 1, email } }
@@ -123,12 +165,12 @@ export const doWork = pikkuFunc({
     assert.equal(hit, undefined)
   })
 
-  test('flags a function that returns a typed alias with Private field', async () => {
+  test('flags a sessionless function that returns a typed alias with Private field', async () => {
     const criticals = await runInspect(`
 ${BRAND_TYPES}
-import { pikkuFunc } from '@pikku/core'
+import { pikkuSessionlessFunc } from '@pikku/core'
 type UserRow = { id: number; email: Private<string> }
-export const getUser = pikkuFunc({
+export const getUser = pikkuSessionlessFunc({
   func: async (): Promise<UserRow> => {
     return { id: 1, email: 'x' as Private<string> }
   }
@@ -139,17 +181,17 @@ export const getUser = pikkuFunc({
     assert.match(hit.message, /email/)
   })
 
-  test('flags across multiple functions in the same file', async () => {
+  test('flags across multiple sessionless functions in the same file', async () => {
     const criticals = await runInspect(`
 ${BRAND_TYPES}
-import { pikkuFunc } from '@pikku/core'
-export const getEmail = pikkuFunc({
+import { pikkuSessionlessFunc } from '@pikku/core'
+export const getEmail = pikkuSessionlessFunc({
   func: async () => ({ email: 'x' as Private<string> })
 })
-export const getPhone = pikkuFunc({
+export const getPhone = pikkuSessionlessFunc({
   func: async () => ({ phone: '555' as Private<string> })
 })
-export const getSafe = pikkuFunc({
+export const getSafe = pikkuSessionlessFunc({
   func: async () => ({ name: 'Alice' })
 })
 `)
@@ -157,11 +199,11 @@ export const getSafe = pikkuFunc({
     assert.equal(hits.length, 2, `Expected 2 PKU910 but got ${hits.length}`)
   })
 
-  test('flags branded values inside arrays', async () => {
+  test('flags branded values inside arrays (sessionless)', async () => {
     const criticals = await runInspect(`
 ${BRAND_TYPES}
-import { pikkuFunc } from '@pikku/core'
-export const getEmails = pikkuFunc({
+import { pikkuSessionlessFunc } from '@pikku/core'
+export const getEmails = pikkuSessionlessFunc({
   func: async () => ({ emails: ['x@y.com' as Private<string>] })
 })
 `)
@@ -170,11 +212,11 @@ export const getEmails = pikkuFunc({
     assert.match(hit.message, /emails/)
   })
 
-  test('flags branded values inside string-indexed records', async () => {
+  test('flags branded values inside string-indexed records (sessionless)', async () => {
     const criticals = await runInspect(`
 ${BRAND_TYPES}
-import { pikkuFunc } from '@pikku/core'
-export const getMap = pikkuFunc({
+import { pikkuSessionlessFunc } from '@pikku/core'
+export const getMap = pikkuSessionlessFunc({
   func: async () => ({ byId: { a: 'x@y.com' as Private<string> } as Record<string, Private<string>> })
 })
 `)
@@ -186,8 +228,8 @@ export const getMap = pikkuFunc({
   test('does not flag when branded field is stripped before return', async () => {
     const criticals = await runInspect(`
 ${BRAND_TYPES}
-import { pikkuFunc } from '@pikku/core'
-export const getUser = pikkuFunc({
+import { pikkuSessionlessFunc } from '@pikku/core'
+export const getUser = pikkuSessionlessFunc({
   func: async () => {
     const raw: { email: Private<string> } = { email: 'x' as Private<string> }
     const safe: { email: string } = { email: raw.email as string }

package/src/utils/check-pii-output.ts

@@ -1,16 +1,22 @@
 import * as ts from 'typescript'
 
+export type ClassifiedField = {
+  path: string
+  classification: 'private' | 'pii' | 'secret' | string
+}
+
 /**
  * Recursively walks a resolved TypeScript type looking for `__classification__` brands —
- * the structural marker emitted by `Private<T>` and `Secret<T>`.
+ * the structural marker emitted by `Private<T>`, `Pii<T>`, and `Secret<T>`.
  *
  * `Private<T> = T & { readonly __classification__: 'private' }` shows up in the TS type
  * system as an intersection whose constituents include a type with a `__classification__`
  * property.  We detect that by checking whether any constituent of an
  * intersection exposes a property named `__classification__`.
  *
- * Returns the list of dotted field paths where a brand was found
- * (e.g. `['email', 'address.phone']`).  An empty array means clean.
+ * Returns the list of classified fields found, each with its dotted path and
+ * classification level (e.g. `[{ path: 'email', classification: 'private' }]`).
+ * An empty array means clean.
  */
 export function findPiiPaths(
   checker: ts.TypeChecker,
@@ -18,23 +24,33 @@ export function findPiiPaths(
   path = '',
   depth = 0,
   seen = new Set<ts.Type>()
-): string[] {
+): ClassifiedField[] {
   if (depth > 8 || seen.has(type)) return []
   seen.add(type)
 
   // ── Is this type itself branded? ─────────────────────────────────────────
   // Private<T> = T & { readonly __classification__: 'private' }  →  isIntersection()
-  // where one constituent has a `__classification__` property.
+  // where one constituent has a `__classification__` property whose type is a string literal.
   if (type.isIntersection()) {
-    const branded = type.types.some((t) =>
-      t.getProperties().some((p) => p.name === '__classification__')
-    )
-    if (branded) {
-      return [path || '<return value>']
+    for (const t of type.types) {
+      const classificationProp = t
+        .getProperties()
+        .find((p) => p.name === '__classification__')
+      if (classificationProp) {
+        const decl =
+          classificationProp.valueDeclaration ??
+          classificationProp.declarations?.[0]
+        const classification = decl
+          ? ((
+              checker.getTypeOfSymbolAtLocation(classificationProp, decl) as any
+            )?.value ?? 'private')
+          : 'private'
+        return [{ path: path || '<return value>', classification }]
+      }
     }
   }
 
-  const violations: string[] = []
+  const violations: ClassifiedField[] = []
 
   // ── Union: check every branch ─────────────────────────────────────────────
   if (type.isUnion()) {

package/src/utils/custom-types-generator.test.ts

@@ -0,0 +1,99 @@
+import { test, describe } from 'node:test'
+import { strict as assert } from 'node:assert'
+import { generateCustomTypes } from './custom-types-generator.js'
+import { TypesMap } from '../types-map.js'
+
+function makeTypesMap(
+  entries: Record<string, { type: string; references: string[] }>
+): TypesMap {
+  const tm = new TypesMap()
+  for (const [name, { type, references }] of Object.entries(entries)) {
+    tm.addCustomType(name, type, references)
+  }
+  return tm
+}
+
+describe('generateCustomTypes — classification wrapper stripping', () => {
+  test('strips Private<T> wrapper from type alias', () => {
+    const tm = makeTypesMap({
+      UserEmail: { type: 'Private<string>', references: ['Private'] },
+    })
+    const result = generateCustomTypes(tm, new Set())
+    assert.match(result, /UserEmail/, 'should emit UserEmail alias')
+    assert.match(
+      result,
+      /= string/,
+      'Private<string> should be stripped to string'
+    )
+    assert.doesNotMatch(result, /Private/, 'Private wrapper must be removed')
+  })
+
+  test('strips Secret<T> wrapper from type alias', () => {
+    const tm = makeTypesMap({
+      HashedPw: { type: 'Secret<string>', references: ['Secret'] },
+    })
+    const result = generateCustomTypes(tm, new Set())
+    assert.match(result, /HashedPw/)
+    assert.match(
+      result,
+      /= string/,
+      'Secret<string> should be stripped to string'
+    )
+    assert.doesNotMatch(result, /Secret/, 'Secret wrapper must be removed')
+  })
+
+  test('strips Pii<T> wrapper from type alias', () => {
+    const tm = makeTypesMap({
+      UserPhone: { type: 'Pii<string>', references: ['Pii'] },
+    })
+    const result = generateCustomTypes(tm, new Set())
+    assert.match(result, /UserPhone/)
+    assert.match(result, /= string/, 'Pii<string> should be stripped to string')
+    assert.doesNotMatch(result, /Pii/, 'Pii wrapper must be removed')
+  })
+
+  test('strips nested classification wrappers', () => {
+    const tm = makeTypesMap({
+      Combo: {
+        type: 'Private<Secret<string>>',
+        references: ['Private', 'Secret'],
+      },
+    })
+    const result = generateCustomTypes(tm, new Set())
+    assert.match(result, /Combo/)
+    assert.match(
+      result,
+      /= string/,
+      'nested wrappers should resolve to inner type'
+    )
+    assert.doesNotMatch(
+      result,
+      /Private|Secret/,
+      'all wrappers must be removed'
+    )
+  })
+
+  test('does not strip non-classification type names', () => {
+    const tm = makeTypesMap({
+      MyType: { type: 'SomeOtherType', references: ['SomeOtherType'] },
+    })
+    const required = new Set<string>()
+    generateCustomTypes(tm, required)
+    assert.ok(
+      required.has('SomeOtherType'),
+      'non-classification references must remain in requiredTypes'
+    )
+  })
+
+  test('classification wrapper references are not added to requiredTypes', () => {
+    const tm = makeTypesMap({
+      SensitiveField: { type: 'Private<string>', references: ['Private'] },
+    })
+    const required = new Set<string>()
+    generateCustomTypes(tm, required)
+    assert.ok(
+      !required.has('Private'),
+      'Private must not be added to requiredTypes'
+    )
+  })
+})

package/src/utils/custom-types-generator.ts

@@ -11,6 +11,61 @@ export function sanitizeTypeName(name: string): string {
   return name.replace(/[^a-zA-Z0-9_$]/g, '_')
 }
 
+const CLASSIFICATION_WRAPPERS = new Set(['Private', 'Pii', 'Secret'])
+
+function findMatchingAngleBracket(type: string, startIndex: number): number {
+  let depth = 0
+  for (let i = startIndex; i < type.length; i += 1) {
+    const char = type[i]
+    if (char === '<') {
+      depth += 1
+      continue
+    }
+    if (char === '>' && (i === 0 || type[i - 1] !== '=')) {
+      depth -= 1
+      if (depth === 0) {
+        return i
+      }
+    }
+  }
+  return -1
+}
+
+function stripClassificationWrappers(type: string): string {
+  let output = ''
+  let index = 0
+
+  while (index < type.length) {
+    const char = type[index]
+    if (!/[A-Za-z_$]/.test(char)) {
+      output += char
+      index += 1
+      continue
+    }
+
+    let end = index + 1
+    while (end < type.length && /[A-Za-z0-9_$]/.test(type[end])) {
+      end += 1
+    }
+
+    const identifier = type.slice(index, end)
+    if (CLASSIFICATION_WRAPPERS.has(identifier) && type[end] === '<') {
+      const closingIndex = findMatchingAngleBracket(type, end)
+      if (closingIndex !== -1) {
+        const inner = type.slice(end + 1, closingIndex)
+        output += stripClassificationWrappers(inner)
+        index = closingIndex + 1
+        continue
+      }
+    }
+
+    output += identifier
+    index = end
+  }
+
+  return output
+}
+
 export function generateCustomTypes(
   typesMap: TypesMap,
   requiredTypes: Set<string>
@@ -25,12 +80,16 @@ export function generateCustomTypes(
     .map(([originalName, { type, references }]) => {
       const name = sanitizeTypeName(originalName)
       references.forEach((refName) => {
-        if (refName !== '__object' && !refName.startsWith('__object_')) {
+        if (
+          refName !== '__object' &&
+          !refName.startsWith('__object_') &&
+          !CLASSIFICATION_WRAPPERS.has(refName)
+        ) {
           requiredTypes.add(refName)
         }
       })
 
-      const typeString = type
+      const typeString = stripClassificationWrappers(type)
       const typeNameRegex = /\b[A-Z][a-zA-Z0-9]*\b/g
       const potentialTypes = typeString.match(typeNameRegex) || []
 
@@ -59,12 +118,13 @@ export function generateCustomTypes(
         }
       })
 
-      if (name === type) return null
-      return `export type ${name} = ${type}`
+      if (name === typeString) return null
+      return `export type ${name} = ${typeString}`
     })
 
   const importsByPath = new Map<string, Set<string>>()
   for (const typeName of requiredTypes) {
+    if (CLASSIFICATION_WRAPPERS.has(typeName)) continue
     try {
       const typeMeta = typesMap.getTypeMeta(typeName)
       if (typeMeta.path) {

package/src/utils/ensure-function-metadata.ts

@@ -280,7 +280,9 @@ export function ensureFunctionMetadata(
           const { tags } = getCommonWireMetaData(
             firstArg,
             'Function',
-            fallbackName || pikkuFuncId
+            fallbackName || pikkuFuncId,
+            undefined,
+            checker
           )
           if (tags) {
             meta.tags = tags

package/src/utils/extract-node-value.test.ts

@@ -46,18 +46,20 @@ describe('extractDescription', () => {
     assert.equal(extractDescription(obj, checker), 'my step')
   })
 
-  test('returns null for non-literal description value without crashing', () => {
+  test('extracts concatenated string literals in description', () => {
     const { checker, sourceFile } = createChecker(
-      `const name = 'test'; const data = { description: name + ' addon' }`
+      `const data = { description: 'line one ' + 'line two' }`
     )
-    const objs: ts.ObjectLiteralExpression[] = []
-    const visit = (node: ts.Node) => {
-      if (ts.isObjectLiteralExpression(node)) objs.push(node)
-      ts.forEachChild(node, visit)
-    }
-    ts.forEachChild(sourceFile, visit)
-    const dataObj = objs[objs.length - 1]!
-    assert.equal(extractDescription(dataObj, checker), null)
+    const obj = findObjectLiteral(sourceFile)!
+    assert.equal(extractDescription(obj, checker), 'line one line two')
+  })
+
+  test('extracts deeply nested concatenation in description', () => {
+    const { checker, sourceFile } = createChecker(
+      `const data = { description: 'a' + 'b' + 'c' }`
+    )
+    const obj = findObjectLiteral(sourceFile)!
+    assert.equal(extractDescription(obj, checker), 'abc')
   })
 
   test('returns null for non-object node', () => {

package/src/utils/extract-node-value.ts

@@ -32,6 +32,16 @@ export function extractStringLiteral(
     return extractStringLiteral(node.expression, checker)
   }
 
+  if (
+    ts.isBinaryExpression(node) &&
+    node.operatorToken.kind === ts.SyntaxKind.PlusToken
+  ) {
+    return (
+      extractStringLiteral(node.left, checker) +
+      extractStringLiteral(node.right, checker)
+    )
+  }
+
   // Try to evaluate constant identifiers
   if (ts.isIdentifier(node)) {
     const symbol = checker.getSymbolAtLocation(node)
@@ -52,7 +62,7 @@ export function extractStringLiteral(
 /**
  * Check if node is string-like (string literal or template expression)
  */
-export function isStringLike(node: ts.Node, _checker: ts.TypeChecker): boolean {
+export function isStringLike(node: ts.Node, checker: ts.TypeChecker): boolean {
   if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
     return true
   }
@@ -60,6 +70,10 @@ export function isStringLike(node: ts.Node, _checker: ts.TypeChecker): boolean {
   if (ts.isTemplateExpression(node)) {
     return true
   }
+  // Unwrap type assertions: `expr as Type` or `<Type>expr`
+  if (ts.isAsExpression(node) || ts.isTypeAssertionExpression(node)) {
+    return isStringLike(node.expression, checker)
+  }
   return false
 }
 

package/src/utils/get-property-value.ts

@@ -1,5 +1,6 @@
 import * as ts from 'typescript'
 import { ErrorCode } from '../error-codes.js'
+import { extractStringLiteral } from './extract-node-value.js'
 
 /**
  * Extracts an array of strings from an object property.
@@ -137,7 +138,8 @@ export const getCommonWireMetaData = (
   obj: ts.ObjectLiteralExpression,
   wiringType: string,
   wiringName: string | null,
-  logger?: { critical: (code: ErrorCode, message: string) => void }
+  logger?: { critical: (code: ErrorCode, message: string) => void },
+  checker?: ts.TypeChecker
 ): {
   disabled?: true
   title?: string
@@ -166,18 +168,36 @@ export const getCommonWireMetaData = (
         prop.initializer.kind === ts.SyntaxKind.TrueKeyword
       ) {
         metadata.disabled = true
-      } else if (propName === 'title' && ts.isStringLiteral(prop.initializer)) {
-        metadata.title = prop.initializer.text
-      } else if (
-        propName === 'summary' &&
-        ts.isStringLiteral(prop.initializer)
-      ) {
-        metadata.summary = prop.initializer.text
-      } else if (
-        propName === 'description' &&
-        ts.isStringLiteral(prop.initializer)
-      ) {
-        metadata.description = prop.initializer.text
+      } else if (propName === 'title') {
+        try {
+          metadata.title = checker
+            ? extractStringLiteral(prop.initializer, checker)
+            : ts.isStringLiteral(prop.initializer)
+              ? prop.initializer.text
+              : undefined
+        } catch {
+          // non-static title — skip
+        }
+      } else if (propName === 'summary') {
+        try {
+          metadata.summary = checker
+            ? extractStringLiteral(prop.initializer, checker)
+            : ts.isStringLiteral(prop.initializer)
+              ? prop.initializer.text
+              : undefined
+        } catch {
+          // non-static summary — skip
+        }
+      } else if (propName === 'description') {
+        try {
+          metadata.description = checker
+            ? extractStringLiteral(prop.initializer, checker)
+            : ts.isStringLiteral(prop.initializer)
+              ? prop.initializer.text
+              : undefined
+        } catch {
+          // non-static description — skip
+        }
       } else if (propName === 'tags') {
         if (ts.isArrayLiteralExpression(prop.initializer)) {
           metadata.tags = prop.initializer.elements

package/src/utils/schema-generator.ts

@@ -297,7 +297,9 @@ async function batchImportWithRegister(
     logger.debug(`tsx register() batch import failed: ${(e as Error).message}`)
     return null
   } finally {
-    await unregister?.()
+    void Promise.resolve(unregister?.()).catch((e) => {
+      logger.debug(`tsx unregister() failed: ${(e as Error).message}`)
+    })
   }
 }
 
@@ -308,7 +310,7 @@ async function importWithRegister(
   try {
     return await import(sourceFile)
   } finally {
-    await unregister()
+    void Promise.resolve(unregister()).catch(() => {})
   }
 }