@principal-ai/subsystems-core 0.29.0

package/src/auxiliary/validateAreaScopeDisjoint.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from 'bun:test';
+import { validateAreaScopeDisjoint } from './validateAreaScopeDisjoint';
+import type { AuxiliaryManifest } from '../types/auxiliary';
+import type { ExtendedCanvas } from '../types/canvas';
+
+function scopesCanvas(nodes: Array<{ scope: string; paths?: string[] }>): ExtendedCanvas {
+  return {
+    nodes: nodes.map((n, i) => ({
+      id: `s${i}`,
+      type: 'otel-scope',
+      description: `${n.scope} scope`,
+      ...(n.paths !== undefined ? { paths: n.paths } : {}),
+      otel: { scope: n.scope },
+      x: 0, y: 0, width: 100, height: 50,
+    })),
+    edges: [],
+  } as ExtendedCanvas;
+}
+
+describe('validateAreaScopeDisjoint', () => {
+  test('returns no violations when areas and scopes are disjoint', () => {
+    const manifest: AuxiliaryManifest = {
+      areas: [{ name: 'Docs', paths: ['docs'], description: 'd' }],
+    };
+    const violations = validateAreaScopeDisjoint({
+      manifest,
+      scopesCanvas: scopesCanvas([{ scope: 'core', paths: ['packages/subsystems-core/src'] }]),
+    });
+    expect(violations).toHaveLength(0);
+  });
+
+  test('flags exact overlap with a scope path', () => {
+    const manifest: AuxiliaryManifest = {
+      areas: [{ name: 'Core', paths: ['packages/subsystems-core/src'], description: 'd' }],
+    };
+    const violations = validateAreaScopeDisjoint({
+      manifest,
+      scopesCanvas: scopesCanvas([{ scope: 'core', paths: ['packages/subsystems-core/src'] }]),
+    });
+    expect(violations).toHaveLength(1);
+    expect(violations[0].ruleId).toBe('auxiliary-area-scope-overlap');
+  });
+
+  test('flags parent-child overlap (area covering a scope path)', () => {
+    const manifest: AuxiliaryManifest = {
+      areas: [{ name: 'All', paths: ['packages'], description: 'd' }],
+    };
+    const violations = validateAreaScopeDisjoint({
+      manifest,
+      scopesCanvas: scopesCanvas([{ scope: 'core', paths: ['packages/subsystems-core/src'] }]),
+    });
+    expect(violations).toHaveLength(1);
+    expect(violations[0].ruleId).toBe('auxiliary-area-scope-overlap');
+  });
+
+  test('flags parent-child overlap (scope path covering an area)', () => {
+    const manifest: AuxiliaryManifest = {
+      areas: [{ name: 'Inner', paths: ['packages/subsystems-core/src/docs'], description: 'd' }],
+    };
+    const violations = validateAreaScopeDisjoint({
+      manifest,
+      scopesCanvas: scopesCanvas([{ scope: 'core', paths: ['packages/subsystems-core/src'] }]),
+    });
+    expect(violations).toHaveLength(1);
+  });
+
+  test('no scopes canvas means no cross-check', () => {
+    const manifest: AuxiliaryManifest = {
+      areas: [{ name: 'Docs', paths: ['docs'], description: 'd' }],
+    };
+    const violations = validateAreaScopeDisjoint({ manifest });
+    expect(violations).toHaveLength(0);
+  });
+
+  test('scopes without paths impose no constraint', () => {
+    const manifest: AuxiliaryManifest = {
+      areas: [{ name: 'Docs', paths: ['docs'], description: 'd' }],
+    };
+    const violations = validateAreaScopeDisjoint({
+      manifest,
+      scopesCanvas: scopesCanvas([{ scope: 'core' }]),
+    });
+    expect(violations).toHaveLength(0);
+  });
+});

package/src/auxiliary/validateAreaScopeDisjoint.ts

@@ -0,0 +1,72 @@
+/**
+ * Area / Scope Disjointness Validator
+ *
+ * Cross-file check: project-area paths declared in
+ * `auxiliary.manifest.json` must be disjoint from every scope path declared
+ * in `architecture.scopes.canvas`. Areas and scopes carve up the repo into
+ * non-overlapping regions — any overlap (parent-child or otherwise) means a
+ * file is claimed by both an OTEL scope and an auxiliary area, which makes
+ * ownership ambiguous.
+ *
+ * Mirrors `validateScopeNamespaceNesting`'s cross-canvas pattern: takes both
+ * inputs, returns violations.
+ */
+
+import type { AuxiliaryManifest } from '../types/auxiliary';
+import type { ExtendedCanvas } from '../types/canvas';
+import { isOtelScopeNode } from '../types/canvas';
+import { pathsOverlap } from '../events/path-helpers';
+import type { AuxiliaryManifestViolation } from './AuxiliaryManifestValidator';
+
+export interface ValidateAreaScopeDisjointInput {
+  manifest: AuxiliaryManifest;
+  manifestPath?: string;
+  scopesCanvas?: ExtendedCanvas;
+  scopesCanvasPath?: string;
+}
+
+const DEFAULT_MANIFEST_PATH = '.principal-views/auxiliary.manifest.json';
+
+export function validateAreaScopeDisjoint(
+  input: ValidateAreaScopeDisjointInput,
+): AuxiliaryManifestViolation[] {
+  const { manifest, scopesCanvas } = input;
+  const manifestFile = input.manifestPath || DEFAULT_MANIFEST_PATH;
+
+  if (!scopesCanvas) return [];
+
+  const scopePaths: Array<{ scope: string; path: string }> = [];
+  for (const node of scopesCanvas.nodes || []) {
+    if (!isOtelScopeNode(node)) continue;
+    const scope = node.otel?.scope;
+    const paths = node.paths;
+    if (!scope || !paths || paths.length === 0) continue;
+    for (const p of paths) scopePaths.push({ scope, path: p });
+  }
+
+  if (scopePaths.length === 0) return [];
+
+  const violations: AuxiliaryManifestViolation[] = [];
+  const areas = manifest.areas || [];
+
+  areas.forEach((area, areaIdx) => {
+    (area.paths || []).forEach((areaPath, pathIdx) => {
+      for (const sp of scopePaths) {
+        const relationship = pathsOverlap(areaPath, sp.path);
+        if (relationship === 'none') continue;
+
+        violations.push({
+          ruleId: 'auxiliary-area-scope-overlap',
+          severity: 'error',
+          file: manifestFile,
+          path: `areas[${areaIdx}].paths[${pathIdx}]`,
+          message: `Area "${area.name}" path "${areaPath}" overlaps scope "${sp.scope}" path "${sp.path}"`,
+          impact: 'A file claimed by both an OTEL scope and an auxiliary area has ambiguous ownership — the manifest is meant to catalog regions outside the telemetry surface',
+          suggestion: 'Make the area path disjoint from every scope path. If the folder is genuinely runtime code, drop it from the manifest; if it is auxiliary, narrow the scope path or move the folder.',
+        });
+      }
+    });
+  });
+
+  return violations;
+}

package/src/browser-safety.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Browser-safety regression test.
+ *
+ * The package has two entry points:
+ *   - `@principal-ai/subsystems-core` (src/index.ts) — must work in any
+ *     environment, including browsers. It must not transitively import any
+ *     Node.js-only built-in module.
+ *   - `@principal-ai/subsystems-core/node` (src/node.ts) — Node-only.
+ *
+ * This test walks the import graph starting from src/index.ts and fails if
+ * any reachable source file pulls in a forbidden Node built-in. `import type`
+ * lines are erased at compile time and are ignored.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync, statSync } from 'fs';
+import { dirname, resolve } from 'path';
+
+const ENTRY = resolve(import.meta.dir, 'index.ts');
+const SRC_ROOT = resolve(import.meta.dir);
+
+// Node built-ins that don't exist in the browser. `node:` prefix and
+// submodules like `fs/promises` are matched separately.
+const FORBIDDEN_BARE = new Set([
+  'fs',
+  'path',
+  'os',
+  'child_process',
+  'crypto',
+  'http',
+  'https',
+  'net',
+  'tls',
+  'stream',
+  'zlib',
+  'url',
+  'worker_threads',
+  'cluster',
+  'dgram',
+  'dns',
+  'readline',
+  'v8',
+  'vm',
+]);
+
+function isForbidden(spec: string): boolean {
+  if (spec.startsWith('node:')) return true;
+  const root = spec.split('/')[0];
+  return FORBIDDEN_BARE.has(root);
+}
+
+function resolveRelative(from: string, spec: string): string | null {
+  const base = resolve(dirname(from), spec);
+  const candidates = [
+    base,
+    `${base}.ts`,
+    `${base}.tsx`,
+    `${base}/index.ts`,
+    `${base}/index.tsx`,
+  ];
+  for (const c of candidates) {
+    try {
+      const s = statSync(c);
+      if (s.isFile()) return c;
+    } catch {
+      // not a file; keep trying
+    }
+  }
+  return null;
+}
+
+interface ImportRef {
+  spec: string;
+  typeOnly: boolean;
+}
+
+// Strip /* ... */ and // ... so commented-out imports don't trip the regex.
+function stripComments(src: string): string {
+  return src
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:])\/\/[^\n]*/g, '$1');
+}
+
+function extractImports(src: string): ImportRef[] {
+  const cleaned = stripComments(src);
+  const refs: ImportRef[] = [];
+
+  // import ... from 'spec' / import 'spec'
+  const importRe = /^\s*import\s+(type\s+)?(?:[^'"]*?from\s+)?['"]([^'"]+)['"]/gm;
+  let m: RegExpExecArray | null;
+  while ((m = importRe.exec(cleaned))) {
+    refs.push({ spec: m[2], typeOnly: Boolean(m[1]) });
+  }
+
+  // export ... from 'spec' (re-exports — runtime-relevant unless "export type")
+  const exportRe = /^\s*export\s+(type\s+)?(?:\*|\{[^}]*\})\s+from\s+['"]([^'"]+)['"]/gm;
+  while ((m = exportRe.exec(cleaned))) {
+    refs.push({ spec: m[2], typeOnly: Boolean(m[1]) });
+  }
+
+  return refs;
+}
+
+interface LeakReport {
+  chain: string[];
+  forbiddenSpec: string;
+}
+
+function findLeaks(entry: string): LeakReport[] {
+  const visited = new Set<string>();
+  const leaks: LeakReport[] = [];
+
+  function walk(file: string, chain: string[]): void {
+    if (visited.has(file)) return;
+    visited.add(file);
+
+    const rel = file.startsWith(SRC_ROOT) ? file.slice(SRC_ROOT.length + 1) : file;
+    const nextChain = [...chain, rel];
+
+    let src: string;
+    try {
+      src = readFileSync(file, 'utf-8');
+    } catch {
+      return;
+    }
+
+    for (const ref of extractImports(src)) {
+      if (ref.typeOnly) continue;
+
+      // Forbidden Node built-in?
+      if (isForbidden(ref.spec)) {
+        leaks.push({ chain: nextChain, forbiddenSpec: ref.spec });
+        continue;
+      }
+
+      // Relative import — recurse.
+      if (ref.spec.startsWith('.')) {
+        const resolved = resolveRelative(file, ref.spec);
+        if (resolved) walk(resolved, nextChain);
+        continue;
+      }
+
+      // External package — out of scope. We trust the package author to have
+      // shipped a browser-safe entry; if they didn't, that's a separate bug.
+    }
+  }
+
+  walk(entry, []);
+  return leaks;
+}
+
+describe('browser-safe entry (src/index.ts)', () => {
+  test('does not transitively import any Node.js built-in', () => {
+    const leaks = findLeaks(ENTRY);
+
+    if (leaks.length > 0) {
+      const lines = leaks.map((l) => {
+        const arrow = l.chain.join('\n      → ');
+        return `  ✗ imports "${l.forbiddenSpec}" via:\n      → ${arrow}`;
+      });
+      const msg =
+        `Found ${leaks.length} Node.js built-in import(s) reachable from src/index.ts.\n` +
+        `These must move to src/node.ts (or be replaced with a FileSystemAdapter):\n\n` +
+        lines.join('\n\n');
+      throw new Error(msg);
+    }
+
+    expect(leaks).toHaveLength(0);
+  });
+});

package/src/cli/codegen.ts

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+/**
+ * Code Generation CLI
+ *
+ * Generate types from canvas files.
+ *
+ * Usage:
+ *   npx @principal-ai/subsystems-core codegen my-flow.canvas
+ *   npx @principal-ai/subsystems-core codegen --lang typescript --output types/ my-flow.canvas
+ *
+ * Similar to:
+ *   - graphql-codegen (GraphQL)
+ *   - openapi-generator (OpenAPI)
+ *   - protoc (Protobuf)
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { generateTypes, generatorRegistry } from '../codegen/type-generator';
+import type { ExtendedCanvas } from '../types/canvas';
+import type { CodegenOptions } from '../codegen/type-generator';
+
+interface CliOptions {
+  language: 'typescript' | 'python' | 'go' | 'rust';
+  output?: string;
+  readonly?: boolean;
+  strictNullChecks?: boolean;
+  includeDocComments?: boolean;
+  namespace?: string;
+  watch?: boolean;
+}
+
+/**
+ * Parse command line arguments
+ */
+function parseArgs(args: string[]): { options: CliOptions; canvasFiles: string[] } {
+  const options: CliOptions = {
+    language: 'typescript',
+    includeDocComments: true,
+    strictNullChecks: true,
+  };
+
+  const canvasFiles: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    switch (arg) {
+      case '--lang':
+      case '-l':
+        options.language = args[++i] as CliOptions['language'];
+        break;
+      case '--output':
+      case '-o':
+        options.output = args[++i];
+        break;
+      case '--readonly':
+        options.readonly = true;
+        break;
+      case '--no-strict-null-checks':
+        options.strictNullChecks = false;
+        break;
+      case '--no-doc-comments':
+        options.includeDocComments = false;
+        break;
+      case '--namespace':
+      case '-n':
+        options.namespace = args[++i];
+        break;
+      case '--watch':
+      case '-w':
+        options.watch = true;
+        break;
+      case '--help':
+      case '-h':
+        printHelp();
+        process.exit(0);
+        break;
+      case '--list-generators':
+        listGenerators();
+        process.exit(0);
+        break;
+      default:
+        if (!arg.startsWith('--')) {
+          canvasFiles.push(arg);
+        }
+    }
+  }
+
+  return { options, canvasFiles };
+}
+
+/**
+ * Generate types for a canvas file
+ */
+function generateTypesForFile(canvasPath: string, options: CliOptions) {
+  console.log(`📝 Generating types from ${canvasPath}...`);
+
+  // Read canvas file
+  const canvas: ExtendedCanvas = JSON.parse(fs.readFileSync(canvasPath, 'utf-8'));
+
+  // Generate types
+  const codegenOptions: CodegenOptions = {
+    language: options.language,
+    style: {
+      readonly: options.readonly,
+      strictNullChecks: options.strictNullChecks,
+      includeDocComments: options.includeDocComments,
+    },
+    namespace: options.namespace,
+  };
+
+  const result = generateTypes(canvas, codegenOptions);
+
+  // Determine output path
+  let outputPath: string;
+  if (options.output) {
+    // If output is a directory, use generated filename
+    if (fs.existsSync(options.output) && fs.statSync(options.output).isDirectory()) {
+      outputPath = path.join(options.output, result.filename);
+    } else {
+      outputPath = options.output;
+    }
+  } else {
+    // Default: packages/subsystems-core/src/generated/ for .principal-views canvases
+    // This keeps canvas files in .principal-views/ but generates types to idiomatic locations
+    const canvasDir = path.dirname(canvasPath);
+    const canvasAbsPath = path.resolve(canvasPath);
+
+    if (canvasAbsPath.includes('.principal-views')) {
+      // Canvas is in .principal-views/, output to packages/subsystems-core/src/generated/
+      const repoRoot = canvasAbsPath.split('.principal-views')[0];
+      const generatedDir = path.join(repoRoot, 'packages', 'core', 'src', 'generated');
+      outputPath = path.join(generatedDir, result.filename);
+    } else {
+      // Canvas is elsewhere, use same directory
+      outputPath = path.join(canvasDir, result.filename);
+    }
+  }
+
+  // Ensure output directory exists
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Write types file
+  fs.writeFileSync(outputPath, result.code);
+
+  console.log(`✅ Generated ${outputPath}`);
+  console.log(`   Language: ${options.language}`);
+  console.log(`   Size: ${result.code.length} bytes`);
+
+  return outputPath;
+}
+
+/**
+ * Print help message
+ */
+function printHelp() {
+  console.log(`
+Code Generation CLI - Generate types from canvas files
+
+USAGE:
+  npx @principal-ai/subsystems-core codegen [OPTIONS] <canvas-files...>
+
+OPTIONS:
+  -l, --lang <language>           Target language (typescript|python|go|rust) [default: typescript]
+  -o, --output <path>             Output file or directory [default: same as canvas]
+  -n, --namespace <name>          Wrap types in a namespace
+  --readonly                      Use readonly modifiers (TypeScript)
+  --no-strict-null-checks         Disable strict null checks
+  --no-doc-comments               Omit JSDoc comments
+  -w, --watch                     Watch for changes and regenerate
+  --list-generators               List available code generators
+  -h, --help                      Show this help message
+
+EXAMPLES:
+  # Generate TypeScript types
+  npx @principal-ai/subsystems-core codegen my-flow.canvas
+
+  # Generate with namespace
+  npx @principal-ai/subsystems-core codegen --namespace Events my-flow.canvas
+
+  # Generate to specific output directory
+  npx @principal-ai/subsystems-core codegen --output src/types/ my-flow.canvas
+
+  # Generate multiple files
+  npx @principal-ai/subsystems-core codegen *.canvas
+
+  # Watch mode (future)
+  npx @principal-ai/subsystems-core codegen --watch my-flow.canvas
+
+PRECEDENTS:
+  This tool follows patterns from:
+  - GraphQL Code Generator (graphql-code-generator.com)
+  - OpenAPI Generator (openapi-generator.tech)
+  - Protobuf Compiler (protoc)
+
+  Like these tools, it generates type-safe code from declarative schemas.
+`);
+}
+
+/**
+ * List available generators
+ */
+function listGenerators() {
+  console.log('\nAvailable Code Generators:\n');
+
+  const languages = generatorRegistry.list();
+
+  for (const lang of languages) {
+    const generator = generatorRegistry.get(lang);
+    console.log(`  • ${lang.padEnd(15)} ${generator ? '✓' : '✗'}`);
+  }
+
+  console.log('\nTo add support for more languages, implement the CodeGenerator interface.');
+  console.log('See: packages/subsystems-core/src/codegen/type-generator.ts\n');
+}
+
+/**
+ * Main entry point
+ */
+function main() {
+  const { options, canvasFiles } = parseArgs(process.argv.slice(2));
+
+  if (canvasFiles.length === 0) {
+    console.error('❌ Error: No canvas files specified\n');
+    printHelp();
+    process.exit(1);
+  }
+
+  // Validate language
+  const availableLanguages = generatorRegistry.list();
+  if (!availableLanguages.includes(options.language)) {
+    console.error(`❌ Error: Unsupported language '${options.language}'`);
+    console.error(`   Available: ${availableLanguages.join(', ')}\n`);
+    listGenerators();
+    process.exit(1);
+  }
+
+  // Generate types for each file
+  const outputFiles: string[] = [];
+
+  for (const canvasFile of canvasFiles) {
+    try {
+      // Check if file exists
+      if (!fs.existsSync(canvasFile)) {
+        console.error(`❌ Error: File not found: ${canvasFile}`);
+        continue;
+      }
+
+      const outputPath = generateTypesForFile(canvasFile, options);
+      outputFiles.push(outputPath);
+    } catch (error) {
+      console.error(`❌ Error processing ${canvasFile}:`, error);
+      process.exit(1);
+    }
+  }
+
+  console.log(`\n✨ Successfully generated ${outputFiles.length} type file(s)\n`);
+
+  // Watch mode
+  if (options.watch) {
+    console.log('👀 Watching for changes...');
+    for (const canvasFile of canvasFiles) {
+      fs.watch(canvasFile, (eventType) => {
+        if (eventType === 'change') {
+          console.log(`\n🔄 ${canvasFile} changed, regenerating...`);
+          try {
+            generateTypesForFile(canvasFile, options);
+          } catch (error) {
+            console.error('❌ Error:', error);
+          }
+        }
+      });
+    }
+  }
+}
+
+// Run CLI if executed directly
+if (require.main === module) {
+  main();
+}
+
+export { main, parseArgs, generateTypesForFile };