@pikku/inspector 0.12.12 → 0.12.13

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+## 0.12.13
+
+### Patch Changes
+
+- 665bdb0: Add end-to-end data classification for SQLite and Postgres projects.
+
+  **Core (`@pikku/core`):** New `Private<T>` and `Secret<T>` intersection brands, `ClassificationManifest`, `ColumnClassification`, and `AnonymizeStrategy` types exported from `data-classification.ts`.
+
+  **CLI (`@pikku/cli`):**
+  - SQL comment annotations: `-- @public`, `-- @private[:strategy]`, `-- @secret[:strategy]` on `CREATE TABLE` columns and `ALTER TABLE ... ADD COLUMN` statements. Unannotated columns default to `private`.
+  - `pikku db migrate` now emits a `classification.gen.ts` manifest alongside `schema.d.ts`.
+  - New `pikku db audit` command — prints a per-column classification summary and warns on `private`/`secret` columns with no anonymize strategy.
+  - Postgres dialect support in `resolveDb`, `PostgresMigrationExecutor`, and `PostgresIntrospector`.
+
+  **Inspector (`@pikku/inspector`):** New PKU910 check — `findPiiPaths()` walks inferred function return types looking for `__pii__` brands (including inside `Array<T>`, `Record<K,V>`, and index signatures) and fails the build if a function exposes branded fields in its output.
+
+- Updated dependencies [665bdb0]
+  - @pikku/core@0.12.25
+
 ## 0.12.12
 
 ### Patch Changes

package/dist/add/add-functions.js

@@ -10,6 +10,7 @@ import { resolveMiddleware } from '../utils/middleware.js';
 import { resolvePermissions } from '../utils/permissions.js';
 import { extractWireNames } from '../utils/post-process.js';
 import { ErrorCode } from '../error-codes.js';
+import { findPiiPaths } from '../utils/check-pii-output.js';
 const isValidVariableName = (name) => {
     const regex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
     return regex.test(name);
@@ -626,6 +627,25 @@ export const addFunctions = (logger, node, checker, state, options) => {
             }
         }
     }
+    // ── PII brand check ───────────────────────────────────────────────────────
+    // Walk the function body's ACTUAL inferred return type looking for Private<T>
+    // / Secret<T> brands (__pii__ property).  This runs for every function,
+    // including those with a Zod output schema, because the TS return type
+    // reflects what the body actually returns before any Zod coercion.
+    {
+        const sig = checker.getSignatureFromDeclaration(handler);
+        if (sig) {
+            const rawRet = checker.getReturnTypeOfSignature(sig);
+            const unwrapped = unwrapPromise(checker, rawRet);
+            const piiPaths = findPiiPaths(checker, unwrapped);
+            if (piiPaths.length > 0) {
+                logger.critical(ErrorCode.PII_IN_OUTPUT, `Function '${name}' exposes PII-classified field(s) in its return type: ` +
+                    piiPaths.map((p) => `'${p}'`).join(', ') +
+                    `.\n  Either strip these fields before returning or mark the column ` +
+                    `@public in the migration if it is safe to expose.`);
+            }
+        }
+    }
     // --- resolve middleware ---
     let middleware = objectNode
         ? resolveMiddleware(state, objectNode, tags, checker)

package/dist/error-codes.d.ts

@@ -54,5 +54,6 @@ export declare enum ErrorCode {
     SCHEMA_AND_WIRING_COLOCATED = "PKU490",
     SERVICES_NOT_DESTRUCTURED = "PKU410",
     WIRES_NOT_DESTRUCTURED = "PKU411",
-    WORKFLOW_MULTI_QUEUE_NOT_SUPPORTED = "PKU901"
+    WORKFLOW_MULTI_QUEUE_NOT_SUPPORTED = "PKU901",
+    PII_IN_OUTPUT = "PKU910"
 }

package/dist/error-codes.js

@@ -67,4 +67,6 @@ export var ErrorCode;
     ErrorCode["WIRES_NOT_DESTRUCTURED"] = "PKU411";
     // Feature Flag
     ErrorCode["WORKFLOW_MULTI_QUEUE_NOT_SUPPORTED"] = "PKU901";
+    // Data classification errors
+    ErrorCode["PII_IN_OUTPUT"] = "PKU910";
 })(ErrorCode || (ErrorCode = {}));

package/dist/utils/check-pii-output.d.ts

@@ -0,0 +1,14 @@
+import * as ts from 'typescript';
+/**
+ * Recursively walks a resolved TypeScript type looking for `__pii__` brands —
+ * the structural marker emitted by `Private<T>` and `Secret<T>`.
+ *
+ * `Private<T> = T & { readonly __pii__: 'private' }` shows up in the TS type
+ * system as an intersection whose constituents include a type with a `__pii__`
+ * property.  We detect that by checking whether any constituent of an
+ * intersection exposes a property named `__pii__`.
+ *
+ * Returns the list of dotted field paths where a brand was found
+ * (e.g. `['email', 'address.phone']`).  An empty array means clean.
+ */
+export declare function findPiiPaths(checker: ts.TypeChecker, type: ts.Type, path?: string, depth?: number, seen?: Set<ts.Type>): string[];

package/dist/utils/check-pii-output.js

@@ -0,0 +1,63 @@
+import * as ts from 'typescript';
+/**
+ * Recursively walks a resolved TypeScript type looking for `__pii__` brands —
+ * the structural marker emitted by `Private<T>` and `Secret<T>`.
+ *
+ * `Private<T> = T & { readonly __pii__: 'private' }` shows up in the TS type
+ * system as an intersection whose constituents include a type with a `__pii__`
+ * property.  We detect that by checking whether any constituent of an
+ * intersection exposes a property named `__pii__`.
+ *
+ * Returns the list of dotted field paths where a brand was found
+ * (e.g. `['email', 'address.phone']`).  An empty array means clean.
+ */
+export function findPiiPaths(checker, type, path = '', depth = 0, seen = new Set()) {
+    if (depth > 8 || seen.has(type))
+        return [];
+    seen.add(type);
+    // ── Is this type itself branded? ─────────────────────────────────────────
+    // Private<T> = T & { readonly __pii__: 'private' }  →  isIntersection()
+    // where one constituent has a `__pii__` property.
+    if (type.isIntersection()) {
+        const branded = type.types.some((t) => t.getProperties().some((p) => p.name === '__pii__'));
+        if (branded) {
+            return [path || '<return value>'];
+        }
+    }
+    const violations = [];
+    // ── Union: check every branch ─────────────────────────────────────────────
+    if (type.isUnion()) {
+        for (const branch of type.types) {
+            violations.push(...findPiiPaths(checker, branch, path, depth, seen));
+        }
+        return violations;
+    }
+    // ── Object: recurse into named properties ─────────────────────────────────
+    if (type.flags & ts.TypeFlags.Object) {
+        const ref = type;
+        for (const arg of ref.typeArguments ?? []) {
+            violations.push(...findPiiPaths(checker, arg, path, depth + 1, seen));
+        }
+        const numberIndex = checker.getIndexTypeOfType(type, ts.IndexKind.Number);
+        if (numberIndex) {
+            const idxPath = path ? `${path}[]` : '[]';
+            violations.push(...findPiiPaths(checker, numberIndex, idxPath, depth + 1, seen));
+        }
+        const stringIndex = checker.getIndexTypeOfType(type, ts.IndexKind.String);
+        if (stringIndex) {
+            const idxPath = path ? `${path}[*]` : '[*]';
+            violations.push(...findPiiPaths(checker, stringIndex, idxPath, depth + 1, seen));
+        }
+        for (const prop of type.getProperties()) {
+            if (prop.name.startsWith('__'))
+                continue;
+            const decl = prop.valueDeclaration ?? prop.declarations?.[0];
+            if (!decl)
+                continue;
+            const propType = checker.getTypeOfSymbolAtLocation(prop, decl);
+            const subPath = path ? `${path}.${prop.name}` : prop.name;
+            violations.push(...findPiiPaths(checker, propType, subPath, depth + 1, seen));
+        }
+    }
+    return violations;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.12",
+  "version": "0.12.13",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "type": "module",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.1",
-    "@pikku/core": "^0.12.21",
+    "@pikku/core": "^0.12.25",
     "path-to-regexp": "^8.3.0",
     "ts-json-schema-generator": "^2.5.0",
     "tsx": "^4.21.0",

package/src/add/add-functions.ts

@@ -19,6 +19,7 @@ import { resolveMiddleware } from '../utils/middleware.js'
 import { resolvePermissions } from '../utils/permissions.js'
 import { extractWireNames } from '../utils/post-process.js'
 import { ErrorCode } from '../error-codes.js'
+import { findPiiPaths } from '../utils/check-pii-output.js'
 import type { NodeType } from '@pikku/core/node'
 
 const isValidVariableName = (name: string) => {
@@ -882,6 +883,29 @@ export const addFunctions: AddWiring = (
     }
   }
 
+  // ── PII brand check ───────────────────────────────────────────────────────
+  // Walk the function body's ACTUAL inferred return type looking for Private<T>
+  // / Secret<T> brands (__pii__ property).  This runs for every function,
+  // including those with a Zod output schema, because the TS return type
+  // reflects what the body actually returns before any Zod coercion.
+  {
+    const sig = checker.getSignatureFromDeclaration(handler)
+    if (sig) {
+      const rawRet = checker.getReturnTypeOfSignature(sig)
+      const unwrapped = unwrapPromise(checker, rawRet)
+      const piiPaths = findPiiPaths(checker, unwrapped)
+      if (piiPaths.length > 0) {
+        logger.critical(
+          ErrorCode.PII_IN_OUTPUT,
+          `Function '${name}' exposes PII-classified field(s) in its return type: ` +
+            piiPaths.map((p) => `'${p}'`).join(', ') +
+            `.\n  Either strip these fields before returning or mark the column ` +
+            `@public in the migration if it is safe to expose.`
+        )
+      }
+    }
+  }
+
   // --- resolve middleware ---
   let middleware = objectNode
     ? resolveMiddleware(state, objectNode, tags, checker)

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

@@ -0,0 +1,197 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { inspect } from '../inspector.js'
+import { ErrorCode } from '../error-codes.js'
+import type { InspectorLogger } from '../types.js'
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function makeLogger() {
+  const criticals: Array<{ code: ErrorCode; message: string }> = []
+  const logger: InspectorLogger = {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    critical: (code, message) => criticals.push({ code, message }),
+    hasCriticalErrors: () => criticals.length > 0,
+  }
+  return { logger, criticals }
+}
+
+/**
+ * Inline Private<T>/Secret<T> definitions that the test source files use.
+ * Mirrors what schema.d.ts emits so the TypeScript program sees the correct
+ * structural brand type even without @pikku/core being importable from /tmp.
+ */
+const BRAND_TYPES = `
+type Private<T> = T & { readonly __pii__: 'private' }
+type Secret<T> = T & { readonly __pii__: 'secret' }
+`
+
+async function runInspect(sourceCode: string) {
+  const tmpDir = await mkdtemp(join(tmpdir(), 'pikku-pii-test-'))
+  const file = join(tmpDir, 'funcs.ts')
+  await writeFile(file, sourceCode)
+  const { logger, criticals } = makeLogger()
+  try {
+    await inspect(logger, [file], { rootDir: tmpDir })
+  } finally {
+    await rm(tmpDir, { recursive: true, force: true })
+  }
+  return criticals
+}
+
+// ── findPiiPaths unit tests via full inspect() round-trip ────────────────────
+
+describe('PII output check — PKU910', () => {
+  test('flags a top-level Private<string> field', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuFunc } from '@pikku/core'
+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.ok(hit, `Expected PKU910 but got: ${JSON.stringify(criticals)}`)
+    assert.match(hit.message, /email/)
+  })
+
+  test('flags a top-level Secret<string> field', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuFunc } from '@pikku/core'
+export const getToken = pikkuFunc({
+  func: async () => {
+    const token = 'abc' as Secret<string>
+    return { token }
+  }
+})
+`)
+    const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.ok(hit)
+    assert.match(hit.message, /token/)
+  })
+
+  test('flags a nested Private field', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuFunc } from '@pikku/core'
+export const getProfile = pikkuFunc({
+  func: async () => {
+    const email = 'x@y.com' as Private<string>
+    return { user: { id: 1, email } }
+  }
+})
+`)
+    const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.ok(hit)
+    assert.match(hit.message, /user\.email/)
+  })
+
+  test('does not flag a plain string return', async () => {
+    const criticals = await runInspect(`
+import { pikkuFunc } from '@pikku/core'
+export const getPublicData = pikkuFunc({
+  func: async () => ({ id: 1, status: 'active', count: 42 })
+})
+`)
+    const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.equal(hit, undefined, `Expected no PKU910 but got: ${JSON.stringify(hit)}`)
+  })
+
+  test('does not flag a void-returning function', async () => {
+    const criticals = await runInspect(`
+import { pikkuFunc } from '@pikku/core'
+export const doWork = pikkuFunc({
+  func: async () => { /* no return */ }
+})
+`)
+    const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.equal(hit, undefined)
+  })
+
+  test('flags a function that returns a typed alias with Private field', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuFunc } from '@pikku/core'
+type UserRow = { id: number; email: Private<string> }
+export const getUser = pikkuFunc({
+  func: async (): Promise<UserRow> => {
+    return { id: 1, email: 'x' as Private<string> }
+  }
+})
+`)
+    const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.ok(hit)
+    assert.match(hit.message, /email/)
+  })
+
+  test('flags across multiple functions in the same file', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuFunc } from '@pikku/core'
+export const getEmail = pikkuFunc({
+  func: async () => ({ email: 'x' as Private<string> })
+})
+export const getPhone = pikkuFunc({
+  func: async () => ({ phone: '555' as Private<string> })
+})
+export const getSafe = pikkuFunc({
+  func: async () => ({ name: 'Alice' })
+})
+`)
+    const hits = criticals.filter((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.equal(hits.length, 2, `Expected 2 PKU910 but got ${hits.length}`)
+  })
+
+  test('flags branded values inside arrays', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuFunc } from '@pikku/core'
+export const getEmails = pikkuFunc({
+  func: async () => ({ emails: ['x@y.com' as Private<string>] })
+})
+`)
+    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, /emails/)
+  })
+
+  test('flags branded values inside string-indexed records', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuFunc } from '@pikku/core'
+export const getMap = pikkuFunc({
+  func: async () => ({ byId: { a: 'x@y.com' as Private<string> } as Record<string, Private<string>> })
+})
+`)
+    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, /byId/)
+  })
+
+  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({
+  func: async () => {
+    const raw: { email: Private<string> } = { email: 'x' as Private<string> }
+    const safe: { email: string } = { email: raw.email as string }
+    return safe
+  }
+})
+`)
+    // The explicit type annotation on 'safe' strips the brand from the inferred return type
+    const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.equal(hit, undefined)
+  })
+})

package/src/error-codes.ts

@@ -77,4 +77,7 @@ export enum ErrorCode {
 
   // Feature Flag
   WORKFLOW_MULTI_QUEUE_NOT_SUPPORTED = 'PKU901',
+
+  // Data classification errors
+  PII_IN_OUTPUT = 'PKU910',
 }

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

@@ -0,0 +1,76 @@
+import * as ts from 'typescript'
+
+/**
+ * Recursively walks a resolved TypeScript type looking for `__pii__` brands —
+ * the structural marker emitted by `Private<T>` and `Secret<T>`.
+ *
+ * `Private<T> = T & { readonly __pii__: 'private' }` shows up in the TS type
+ * system as an intersection whose constituents include a type with a `__pii__`
+ * property.  We detect that by checking whether any constituent of an
+ * intersection exposes a property named `__pii__`.
+ *
+ * Returns the list of dotted field paths where a brand was found
+ * (e.g. `['email', 'address.phone']`).  An empty array means clean.
+ */
+export function findPiiPaths(
+  checker: ts.TypeChecker,
+  type: ts.Type,
+  path = '',
+  depth = 0,
+  seen = new Set<ts.Type>()
+): string[] {
+  if (depth > 8 || seen.has(type)) return []
+  seen.add(type)
+
+  // ── Is this type itself branded? ─────────────────────────────────────────
+  // Private<T> = T & { readonly __pii__: 'private' }  →  isIntersection()
+  // where one constituent has a `__pii__` property.
+  if (type.isIntersection()) {
+    const branded = type.types.some((t) =>
+      t.getProperties().some((p) => p.name === '__pii__')
+    )
+    if (branded) {
+      return [path || '<return value>']
+    }
+  }
+
+  const violations: string[] = []
+
+  // ── Union: check every branch ─────────────────────────────────────────────
+  if (type.isUnion()) {
+    for (const branch of type.types) {
+      violations.push(...findPiiPaths(checker, branch, path, depth, seen))
+    }
+    return violations
+  }
+
+  // ── Object: recurse into named properties ─────────────────────────────────
+  if (type.flags & ts.TypeFlags.Object) {
+    const ref = type as ts.TypeReference
+    for (const arg of (ref as any).typeArguments ?? []) {
+      violations.push(...findPiiPaths(checker, arg, path, depth + 1, seen))
+    }
+
+    const numberIndex = checker.getIndexTypeOfType(type, ts.IndexKind.Number)
+    if (numberIndex) {
+      const idxPath = path ? `${path}[]` : '[]'
+      violations.push(...findPiiPaths(checker, numberIndex, idxPath, depth + 1, seen))
+    }
+    const stringIndex = checker.getIndexTypeOfType(type, ts.IndexKind.String)
+    if (stringIndex) {
+      const idxPath = path ? `${path}[*]` : '[*]'
+      violations.push(...findPiiPaths(checker, stringIndex, idxPath, depth + 1, seen))
+    }
+
+    for (const prop of type.getProperties()) {
+      if (prop.name.startsWith('__')) continue
+      const decl = prop.valueDeclaration ?? prop.declarations?.[0]
+      if (!decl) continue
+      const propType = checker.getTypeOfSymbolAtLocation(prop, decl)
+      const subPath = path ? `${path}.${prop.name}` : prop.name
+      violations.push(...findPiiPaths(checker, propType, subPath, depth + 1, seen))
+    }
+  }
+
+  return violations
+}