test(metadata): compile every TypeScriptSerializer annotation with tsc

Drops view from the annotation table: ViewMetadata is the input type of a
z.preprocess schema, so it is unknown and would check nothing.

Claude-Session: https://claude.ai/code/session_01TEhopqrWQYBycZzyJHpAZr
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/metadata/src/serializers/serializers.test.ts

@@ -1,4 +1,8 @@
 import { describe, it, expect } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { NodeMetadataManager } from '../node-metadata-manager.js';
 import { JSONSerializer } from '../serializers/json-serializer.js';
 import { YAMLSerializer } from '../serializers/yaml-serializer.js';
 import { TypeScriptSerializer } from '../serializers/typescript-serializer.js';
@@ -55,14 +59,85 @@ describe('Serializers', () => {
   describe('TypeScriptSerializer', () => {
     const serializer = new TypeScriptSerializer('typescript');
 
+    // The saved-view repro: a view used to be annotated `ServiceObject`, which
+    // has no top-level `type` or `columns` key, so `tsc` refused the file (TS2353).
+    const view = { name: 'all_accounts', type: 'grid', object: 'account', columns: ['name'] };
+    const object = { name: 'account', label: 'Account', fields: { name: { type: 'text', label: 'Name' } } };
+
     it('should serialize to TypeScript module', () => {
       const data = { name: 'test', value: 42 };
       const result = serializer.serialize(data);
-      expect(result).toContain('import type');
       expect(result).toContain('export const metadata');
       expect(result).toContain('export default metadata');
     });
 
+    it('writes a view with no annotation: no ServiceObject, no import type', () => {
+      const result = serializer.serialize(view, { metadataType: 'view' });
+      expect(result).not.toContain('ServiceObject');
+      expect(result).toBe(
+        `export const metadata = ${JSON.stringify(view, null, 2)};\n\nexport default metadata;\n`,
+      );
+    });
+
+    it('still annotates an object ServiceObject, byte-identical to the earlier output', () => {
+      const result = serializer.serialize(object, { metadataType: 'object' });
+      expect(result).toBe(
+        `import type { ServiceObject } from '@objectstack/spec/data';\n\n` +
+          `export const metadata: ServiceObject = ${JSON.stringify(object, null, 2)};\n\n` +
+          `export default metadata;\n`,
+      );
+    });
+
+    it.each([
+      ['no metadata type', undefined],
+      ['a metadata type the spec has no type for', 'external_catalog'],
+      ['a metadata type whose spec type is narrower than its schema', 'book'],
+      ['a plugin-registered metadata type', 'acme_widget'],
+      ['a plural spelling', 'objects'],
+    ])('writes no annotation for %s', (_label, metadataType) => {
+      const result = serializer.serialize({ name: 'x' }, { metadataType });
+      expect(result.startsWith('export const metadata = {')).toBe(true);
+      expect(result).not.toContain('import type');
+    });
+
+    it('the javascript format never annotates, whatever the metadata type', () => {
+      const js = new TypeScriptSerializer('javascript');
+      expect(js.serialize(object, { metadataType: 'object' })).toBe(
+        `export const metadata = ${JSON.stringify(object, null, 2)};\n\nexport default metadata;\n`,
+      );
+    });
+
+    it('reads back a file written before this fix: a view annotated ServiceObject', () => {
+      const legacy =
+        `import type { ServiceObject } from '@objectstack/spec/data';\n\n` +
+        `export const metadata: ServiceObject = ${JSON.stringify(view, null, 2)};\n\n` +
+        `export default metadata;\n`;
+      expect(serializer.deserialize(legacy)).toEqual(view);
+    });
+
+    it('round-trips a view and an object through serialize and deserialize', () => {
+      for (const [metadataType, item] of [['view', view], ['object', object]] as const) {
+        expect(serializer.deserialize(serializer.serialize(item, { metadataType }))).toEqual(item);
+      }
+    });
+
+    it('FilesystemLoader.save() passes the metadata type: the view file is unannotated, the object file is ServiceObject', async () => {
+      const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), 'objectstack-ts-serializer-'));
+      try {
+        const manager = new NodeMetadataManager({ rootDir, watch: false });
+        await manager.save('view', 'all_accounts', view);
+        await manager.save('object', 'account', object);
+        const viewFile = await fs.readFile(path.join(rootDir, 'view', 'all_accounts.ts'), 'utf-8');
+        const objectFile = await fs.readFile(path.join(rootDir, 'object', 'account.ts'), 'utf-8');
+        expect(viewFile).toBe(serializer.serialize(view, { metadataType: 'view' }));
+        expect(viewFile).not.toContain('ServiceObject');
+        expect(objectFile).toBe(serializer.serialize(object, { metadataType: 'object' }));
+        expect(objectFile).toContain('export const metadata: ServiceObject = {');
+      } finally {
+        await fs.rm(rootDir, { recursive: true, force: true });
+      }
+    });
+
     it('should get correct extension', () => {
       const ts = new TypeScriptSerializer('typescript');
       expect(ts.getExtension()).toBe('.ts');

packages/metadata/src/serializers/typescript-serializer-annotation.test.ts

@@ -0,0 +1,148 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * `TypeScriptSerializer` annotates a `typescript`-format file with the spec
+ * type of the item's metadata type. This file holds that annotation to the one
+ * property that makes it worth writing: it is never false.
+ *
+ * Every annotated metadata type is compiled here with `tsc`, twice:
+ *  - a spec-valid body must type-check with no diagnostic at all;
+ *  - the same body plus one undeclared key must fail with exactly TS2353. That
+ *    is what makes the annotation a check: a spec type that is `unknown` (as
+ *    `ViewMetadata` is) would pass the first file and the second.
+ *
+ * `@objectstack/spec` is resolved the way a consumer of a saved file resolves
+ * it, through this package's `node_modules` and the `exports` map's `types`,
+ * so this reads spec's BUILT `dist/*.d.ts`. `turbo test` builds it first
+ * (`^build`); a bare `vitest run` needs `pnpm --filter @objectstack/spec build`.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
+import { MetadataTypeSchema, getMetadataTypeSchema } from '@objectstack/spec/kernel';
+import { TypeScriptSerializer } from './typescript-serializer.js';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** One spec-valid body per metadata type the serializer annotates. */
+const REPRESENTATIVE: Record<string, Record<string, unknown>> = {
+  object: { name: 'account', label: 'Account', fields: { name: { type: 'text', label: 'Name' } } },
+  field: { name: 'title', type: 'text', label: 'Title' },
+  hook: { name: 'account_audit', object: 'account', events: ['beforeInsert'], handler: 'audit_account' },
+  seed: { object: 'account', records: [{ name: 'Acme' }] },
+  mapping: { name: 'account_import', targetObject: 'account', fieldMapping: [] },
+  datasource: { name: 'warehouse', driver: 'sqlite', config: {} },
+  analytics_cube: { name: 'account_cube', sql: 'account', measures: {}, dimensions: {} },
+  page: { name: 'account_home', label: 'Account Home', regions: [] },
+  dashboard: { name: 'ops', label: 'Ops', widgets: [] },
+  app: { name: 'sales', label: 'Sales' },
+  action: { name: 'close_account', label: 'Close', type: 'script', target: 'close_account' },
+  report: { name: 'hours_by_status', label: 'Hours by status', dataset: 'task_metrics', rows: ['status'], values: ['est_hours'] },
+  dataset: { name: 'account_ds', label: 'Accounts', object: 'account', dimensions: [], measures: [] },
+  flow: { name: 'notify_owner', label: 'Notify owner', type: 'autolaunched', nodes: [], edges: [] },
+  webhook: { name: 'account_hook', object: 'account', triggers: ['create'], url: 'https://example.com/hook' },
+  job: { name: 'nightly_sweep', schedule: { type: 'cron', expression: '0 2 * * *' }, handler: 'sweep' },
+  translation: { locale: 'en', objects: { account: { label: 'Account' } } },
+  email_template: { name: 'welcome', label: 'Welcome', subject: 'Welcome', bodyHtml: 'Hello' },
+  doc: { name: 'getting_started', label: 'Getting Started', content: '# Hello' },
+  api: { name: 'ping', path: '/api/v1/apps/demo/ping', method: 'GET', type: 'object_operation', target: 'account' },
+  permission: { name: 'sales_user', label: 'Sales user', objects: {} },
+  sharing_rule: {
+    name: 'share_accounts', object: 'account', type: 'criteria', condition: 'true',
+    sharedWith: { type: 'team', value: 'sales' }, accessLevel: 'read',
+  },
+  capability: { name: 'manage_accounts', label: 'Manage accounts' },
+  position: { name: 'sales_rep', label: 'Sales rep' },
+  agent: { name: 'support_agent', label: 'Support', role: 'Support', instructions: 'Help users.', skills: ['case_management'] },
+  tool: { name: 'list_records', label: 'List records', description: 'Lists records', parameters: {} },
+  skill: { name: 'case_management', label: 'Case management', tools: [] },
+  connector: { name: 'status_api', label: 'Status API', type: 'api', authentication: { type: 'none' } },
+};
+
+/** Stack collections `getMetadataTypeSchema()` binds that are not `MetadataTypeSchema` members. */
+const NON_MEMBER_TYPES = ['webhook', 'connector', 'sharing_rule', 'analytics_cube'];
+
+const serializer = new TypeScriptSerializer('typescript');
+const annotates = (metadataType: string): boolean =>
+  serializer.serialize({ name: 'x' }, { metadataType }).startsWith('import type {');
+
+/** Type-check in-memory files as if they sat in this directory. */
+function typeCheck(files: ReadonlyMap<string, string>): readonly ts.Diagnostic[] {
+  const options: ts.CompilerOptions = {
+    strict: true,
+    noEmit: true,
+    skipLibCheck: true,
+    types: [],
+    target: ts.ScriptTarget.ES2022,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+  };
+  const host = ts.createCompilerHost(options, true);
+  const { getSourceFile, fileExists, readFile } = host;
+  host.getSourceFile = (fileName, languageVersion, onError, shouldCreate) => {
+    const text = files.get(fileName);
+    return text === undefined
+      ? getSourceFile.call(host, fileName, languageVersion, onError, shouldCreate)
+      : ts.createSourceFile(fileName, text, languageVersion, true);
+  };
+  host.fileExists = (fileName) => files.has(fileName) || fileExists.call(host, fileName);
+  host.readFile = (fileName) => files.get(fileName) ?? readFile.call(host, fileName);
+  return ts.getPreEmitDiagnostics(ts.createProgram([...files.keys()], options, host));
+}
+
+describe('TypeScriptSerializer annotation, per metadata type', () => {
+  it('every representative body is valid for its metadata type', () => {
+    for (const [metadataType, item] of Object.entries(REPRESENTATIVE)) {
+      const result = getMetadataTypeSchema(metadataType)?.safeParse(item);
+      expect(result?.success, metadataType).toBe(true);
+    }
+  });
+
+  it('annotates exactly the representative metadata types, and never view, book or external_catalog', () => {
+    const universe = new Set([...MetadataTypeSchema.options, ...NON_MEMBER_TYPES, ...Object.keys(REPRESENTATIVE)]);
+    const annotated = [...universe].filter(annotates).sort();
+    expect(annotated).toEqual(Object.keys(REPRESENTATIVE).sort());
+    for (const metadataType of ['view', 'book', 'external_catalog']) {
+      expect(annotates(metadataType), metadataType).toBe(false);
+    }
+  });
+
+  it('round-trips every annotated body through serialize and deserialize', () => {
+    for (const [metadataType, item] of Object.entries(REPRESENTATIVE)) {
+      expect(serializer.deserialize(serializer.serialize(item, { metadataType })), metadataType).toEqual(item);
+    }
+  });
+
+  it('tsc: a valid body type-checks and an undeclared key is refused (TS2353), for every annotation', () => {
+    const dir = join(HERE, '__annotation_type_check__');
+    const files = new Map<string, string>();
+    for (const [metadataType, item] of Object.entries(REPRESENTATIVE)) {
+      const valid = serializer.serialize(item, { metadataType });
+      files.set(join(dir, `${metadataType}.ts`), valid);
+      files.set(join(dir, `${metadataType}.undeclared-key.ts`), valid.replace('= {', '= {\n  "undeclared_key": 1,'));
+    }
+    const diagnostics = typeCheck(files);
+    const byFile = new Map<string, number[]>();
+    const unattributed: string[] = [];
+    for (const d of diagnostics) {
+      if (!d.file) {
+        unattributed.push(ts.flattenDiagnosticMessageText(d.messageText, '\n'));
+        continue;
+      }
+      byFile.set(d.file.fileName, [...(byFile.get(d.file.fileName) ?? []), d.code]);
+    }
+    const report = ts.formatDiagnostics(diagnostics, {
+      getCanonicalFileName: (f) => f,
+      getCurrentDirectory: () => dir,
+      getNewLine: () => '\n',
+    });
+    expect(unattributed, report).toEqual([]);
+    expect([...byFile.keys()].filter((f) => !files.has(f)), report).toEqual([]);
+    for (const metadataType of Object.keys(REPRESENTATIVE)) {
+      expect(byFile.get(join(dir, `${metadataType}.ts`)) ?? [], report).toEqual([]);
+      expect(byFile.get(join(dir, `${metadataType}.undeclared-key.ts`)) ?? [], report).toEqual([2353]);
+    }
+  }, 60_000);
+});

packages/metadata/src/serializers/typescript-serializer.ts

@@ -23,12 +23,18 @@ import type { MetadataSerializer, SerializeOptions } from './serializer-interfac
  * annotation and no `import type`, never `any`, `unknown` or another type's
  * shape.
  *
- * `book` is deliberately absent: `Book` is written by hand and lacks the
- * `_packageId` / `_provenance` protection keys `BookSchema` accepts, so a book
- * the loader has stamped would fail against it.
+ * Two metadata types are deliberately absent:
+ * - `view`: `ViewMetadataSchema` is a `z.preprocess`, so its input type, and
+ *   with it `ViewMetadata`, is `unknown`. Annotating with it would check
+ *   nothing.
+ * - `book`: `Book` is written by hand and lacks the `_packageId` /
+ *   `_provenance` protection keys `BookSchema` accepts, so a book the loader
+ *   has stamped would fail against it.
  *
- * Every entry is compiled with `tsc` in `serializers.test.ts`, so a renamed or
- * moved spec type fails there instead of in a saved file.
+ * `typescript-serializer-annotation.test.ts` compiles every entry with `tsc`:
+ * a valid body must type-check and an undeclared key must not, so a renamed,
+ * moved or widened-to-`unknown` spec type fails there instead of in a saved
+ * file.
  */
 const ANNOTATION_BY_METADATA_TYPE: ReadonlyMap<string, readonly [typeName: string, subpath: string]> = new Map([
   ['object', ['ServiceObject', 'data']],
@@ -38,7 +44,6 @@ const ANNOTATION_BY_METADATA_TYPE: ReadonlyMap<string, readonly [typeName: strin
   ['mapping', ['Mapping', 'data']],
   ['datasource', ['Datasource', 'data']],
   ['analytics_cube', ['Cube', 'data']],
-  ['view', ['ViewMetadata', 'ui']],
   ['page', ['Page', 'ui']],
   ['dashboard', ['Dashboard', 'ui']],
   ['app', ['App', 'ui']],