feat(schemas): validate metadata boundaries with valibot

Author: tuanductran

packages/nextdns-scripts/src/__tests__/public-api.test.ts

@@ -3,7 +3,9 @@ import { describe, expect, it } from 'vitest';
 import {
   AuditCheckSchema,
   AuditReportSchema,
+  PackageMetadataSchema,
   parseAuditReport,
+  parsePackageMetadata,
   parseStatsReport,
   SkillStatsSchema,
   StatsReportSchema,
@@ -15,10 +17,12 @@ describe('maintenance package public schema API', () => {
     expect(AuditReportSchema).toBeDefined();
     expect(SkillStatsSchema).toBeDefined();
     expect(StatsReportSchema).toBeDefined();
+    expect(PackageMetadataSchema).toBeDefined();
   });
 
   it('exports callable report parsers from the package root', () => {
     expect(typeof parseAuditReport).toBe('function');
     expect(typeof parseStatsReport).toBe('function');
+    expect(typeof parsePackageMetadata).toBe('function');
   });
 });

packages/nextdns-scripts/src/__tests__/schemas.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import { parseAuditReport, parseStatsReport } from '../core/schemas.js';
+import { parseAuditReport, parsePackageMetadata, parseStatsReport } from '../core/schemas.js';
 
 const validStatistics = {
   generatedAt: '2026-08-18T00:00:00.000Z',
@@ -111,4 +111,14 @@ describe('schema parsing', () => {
     expect(report.skills[0]?.name).toBe('nextdns-api');
     expect(report.impactDistribution.HIGH).toBe(1);
   });
+
+  it('accepts package metadata with an optional version', () => {
+    expect(parsePackageMetadata({ version: '0.4.0' })).toEqual({ version: '0.4.0' });
+    expect(parsePackageMetadata({})).toEqual({});
+  });
+
+  it('rejects malformed package metadata', () => {
+    expect(() => parsePackageMetadata(null)).toThrow();
+    expect(() => parsePackageMetadata({ version: 4 })).toThrow();
+  });
 });

packages/nextdns-scripts/src/core/schemas.ts

@@ -1,6 +1,11 @@
 import * as v from 'valibot';
 
 const CountSchema = v.pipe(v.number(), v.integer(), v.minValue(0));
+const NonEmptyStringSchema = v.pipe(v.string(), v.minLength(1));
+
+export const PackageMetadataSchema = v.object({
+  version: v.optional(NonEmptyStringSchema),
+});
 
 const AuditCheckNameSchema = v.picklist([
   'referential-integrity',
@@ -53,11 +58,16 @@ export const AuditReportSchema = v.object({
   statistics: StatsReportSchema,
 });
 
+export type PackageMetadata = v.InferOutput<typeof PackageMetadataSchema>;
 export type AuditCheck = v.InferOutput<typeof AuditCheckSchema>;
 export type AuditReport = v.InferOutput<typeof AuditReportSchema>;
 export type SkillStats = v.InferOutput<typeof SkillStatsSchema>;
 export type StatsReport = v.InferOutput<typeof StatsReportSchema>;
 
+export function parsePackageMetadata(input: unknown): PackageMetadata {
+  return v.parse(PackageMetadataSchema, input);
+}
+
 export function parseAuditReport(input: unknown): AuditReport {
   return v.parse(AuditReportSchema, input);
 }

packages/nextdns-scripts/src/core/version.ts

@@ -1,9 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
-interface PackageMetadata {
-  version?: unknown;
-}
+import { parsePackageMetadata } from './schemas.js';
 
 export function getPackageVersion(): string {
   const packagePaths = [
@@ -13,6 +11,10 @@ export function getPackageVersion(): string {
   const packagePath = packagePaths.find((candidate) => existsSync(candidate));
   if (!packagePath) return '0.0.0';
 
-  const metadata = JSON.parse(readFileSync(packagePath, 'utf8')) as PackageMetadata;
-  return typeof metadata.version === 'string' ? metadata.version : '0.0.0';
+  try {
+    const metadata = parsePackageMetadata(JSON.parse(readFileSync(packagePath, 'utf8')));
+    return metadata.version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
 }

packages/nextdns-scripts/src/index.ts

@@ -10,10 +10,12 @@ export { formatAuditText, runAudit } from './commands/audit.js';
 export {
   AuditCheckSchema,
   AuditReportSchema,
+  PackageMetadataSchema,
   parseAuditReport,
+  parsePackageMetadata,
   parseStatsReport,
   SkillStatsSchema,
   StatsReportSchema,
 } from './core/schemas.js';
-export type { SkillStats, StatsReport } from './core/schemas.js';
+export type { PackageMetadata, SkillStats, StatsReport } from './core/schemas.js';
 export { getPackageVersion } from './core/version.js';

packages/nextdns-skills-build/src/__tests__/data-schemas.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from 'vite-plus/test';
+
+import {
+  BuildMetadataSchema,
+  FrontmatterSchema,
+  PackageMetadataSchema,
+  parseBuildMetadata,
+  parseFrontmatter,
+  parsePackageMetadata,
+} from '../core/data-schemas.js';
+import { parseFrontmatter as parseMarkdownFrontmatter } from '../core/markdown.js';
+
+const validBuildMetadata = {
+  version: '1.2.3',
+  organization: 'NextDNS Skills',
+  date: '2026-08-18',
+  abstract: 'Build metadata for the generated skills package.',
+  references: [{ title: 'NextDNS API', url: 'https://api.nextdns.io' }],
+};
+
+describe('data schemas', () => {
+  describe('FrontmatterSchema', () => {
+    it('accepts scalar and string-array frontmatter values', () => {
+      const frontmatter = parseFrontmatter({
+        title: 'Authentication',
+        tags: ['api', 'security'],
+      });
+
+      expect(frontmatter).toEqual({ title: 'Authentication', tags: ['api', 'security'] });
+    });
+
+    it('rejects non-string frontmatter values', () => {
+      expect(() => parseFrontmatter({ tags: ['api', 1] })).toThrow();
+      expect(() => parseFrontmatter({ count: 2 })).toThrow();
+    });
+
+    it('validates frontmatter produced by the markdown parser', () => {
+      const frontmatter = parseMarkdownFrontmatter(`---
+title: 'Authentication'
+tags:
+  - api
+  - security
+---
+
+# Authentication
+`);
+
+      expect(FrontmatterSchema).toBeDefined();
+      expect(frontmatter).toEqual({ title: 'Authentication', tags: ['api', 'security'] });
+    });
+  });
+
+  describe('BuildMetadataSchema', () => {
+    it('accepts complete build metadata with references', () => {
+      const metadata = parseBuildMetadata(validBuildMetadata);
+
+      expect(metadata.version).toBe('1.2.3');
+      expect(metadata.references?.[0]?.url).toBe('https://api.nextdns.io');
+    });
+
+    it('accepts build metadata without optional references', () => {
+      const { references, ...withoutReferences } = validBuildMetadata;
+
+      expect(references).toBeDefined();
+      expect(parseBuildMetadata(withoutReferences).organization).toBe('NextDNS Skills');
+    });
+
+    it('rejects missing required metadata fields', () => {
+      const { abstract, ...withoutAbstract } = validBuildMetadata;
+
+      expect(abstract).toBeDefined();
+      expect(() => parseBuildMetadata(withoutAbstract)).toThrow();
+    });
+
+    it('rejects malformed metadata fields and references', () => {
+      expect(() => parseBuildMetadata({ ...validBuildMetadata, version: 1 })).toThrow();
+      expect(() =>
+        parseBuildMetadata({
+          ...validBuildMetadata,
+          references: [{ title: 'NextDNS API', url: '' }],
+        })
+      ).toThrow();
+    });
+  });
+
+  describe('PackageMetadataSchema', () => {
+    it('accepts package metadata with or without a version', () => {
+      expect(parsePackageMetadata({ version: '0.4.0' }).version).toBe('0.4.0');
+      expect(parsePackageMetadata({})).toEqual({});
+    });
+
+    it('rejects malformed package metadata', () => {
+      expect(() => parsePackageMetadata(null)).toThrow();
+      expect(() => parsePackageMetadata({ version: 4 })).toThrow();
+    });
+
+    it('exposes the schema for runtime composition', () => {
+      expect(BuildMetadataSchema).toBeDefined();
+      expect(PackageMetadataSchema).toBeDefined();
+    });
+  });
+});

packages/nextdns-skills-build/src/__tests__/public-api.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vite-plus/test';
+
+import {
+  BuildMetadataSchema,
+  FrontmatterSchema,
+  FrontmatterValueSchema,
+  PackageMetadataSchema,
+  parseBuildMetadata,
+  parseFrontmatter,
+  parsePackageMetadata,
+} from '../index.js';
+
+describe('build package public schema API', () => {
+  it('exports all data schema objects from the package root', () => {
+    expect(BuildMetadataSchema).toBeDefined();
+    expect(FrontmatterSchema).toBeDefined();
+    expect(FrontmatterValueSchema).toBeDefined();
+    expect(PackageMetadataSchema).toBeDefined();
+  });
+
+  it('exports callable validated parsers from the package root', () => {
+    expect(typeof parseBuildMetadata).toBe('function');
+    expect(typeof parseFrontmatter).toBe('function');
+    expect(typeof parsePackageMetadata).toBe('function');
+  });
+});

packages/nextdns-skills-build/src/commands/build.ts

@@ -11,6 +11,7 @@ import type { Section } from '../core/types.js';
 
 import { parseBuildCliOptions, type BuildCliOptions } from '../core/cli-validation.js';
 import { DEFAULT_SKILL, SKILLS, type SkillConfig } from '../core/config.js';
+import { parseBuildMetadata, type BuildMetadata } from '../core/data-schemas.js';
 import { parseRuleFile, type RuleFile } from '../core/parser.js';
 import { collectRuleFiles } from '../core/utils.js';
 
@@ -29,13 +30,7 @@ function incrementVersion(version: string): string {
  */
 function generateMarkdown(
   sections: Section[],
-  metadata: {
-    version: string;
-    organization: string;
-    date: string;
-    abstract: string;
-    references?: { title: string; url: string }[];
-  },
+  metadata: BuildMetadata,
   skillConfig: SkillConfig
 ): string {
   let md = `# ${skillConfig.title}\n\n`;
@@ -192,16 +187,10 @@ async function buildSkill(skillConfig: SkillConfig, options: BuildCliOptions) {
   const sections = Array.from(sectionsMap.values()).sort((a, b) => a.number - b.number);
 
   // Read metadata
-  let metadata: {
-    version: string;
-    organization: string;
-    date: string;
-    abstract: string;
-    references?: { title: string; url: string }[];
-  };
+  let metadata: BuildMetadata;
   try {
     const metadataContent = await readFile(skillConfig.metadataFile, 'utf-8');
-    metadata = JSON.parse(metadataContent);
+    metadata = parseBuildMetadata(JSON.parse(metadataContent));
   } catch {
     metadata = {
       version: '1.0.0',

packages/nextdns-skills-build/src/core/data-schemas.ts

@@ -0,0 +1,42 @@
+import * as v from 'valibot';
+
+const NonEmptyStringSchema = v.pipe(v.string(), v.minLength(1));
+
+export const FrontmatterValueSchema = v.union([v.string(), v.array(v.string())]);
+export const FrontmatterSchema = v.record(v.string(), FrontmatterValueSchema);
+
+export const BuildMetadataSchema = v.object({
+  version: NonEmptyStringSchema,
+  organization: NonEmptyStringSchema,
+  date: NonEmptyStringSchema,
+  abstract: NonEmptyStringSchema,
+  references: v.optional(
+    v.array(
+      v.object({
+        title: NonEmptyStringSchema,
+        url: NonEmptyStringSchema,
+      })
+    )
+  ),
+});
+
+export const PackageMetadataSchema = v.object({
+  version: v.optional(NonEmptyStringSchema),
+});
+
+export type BuildMetadata = v.InferOutput<typeof BuildMetadataSchema>;
+export type FrontmatterValue = v.InferOutput<typeof FrontmatterValueSchema>;
+export type Frontmatter = v.InferOutput<typeof FrontmatterSchema>;
+export type PackageMetadata = v.InferOutput<typeof PackageMetadataSchema>;
+
+export function parseBuildMetadata(input: unknown): BuildMetadata {
+  return v.parse(BuildMetadataSchema, input);
+}
+
+export function parseFrontmatter(input: unknown): Frontmatter {
+  return v.parse(FrontmatterSchema, input);
+}
+
+export function parsePackageMetadata(input: unknown): PackageMetadata {
+  return v.parse(PackageMetadataSchema, input);
+}

packages/nextdns-skills-build/src/core/markdown.ts

@@ -1,8 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-export type FrontmatterValue = string | string[];
-export type Frontmatter = Record<string, FrontmatterValue>;
+import { parseFrontmatter as validateFrontmatter, type Frontmatter } from './data-schemas.js';
+
+export type { Frontmatter, FrontmatterValue } from './data-schemas.js';
 
 export function parseFrontmatter(content: string): Frontmatter {
   if (!content.startsWith('---')) return {};
@@ -45,7 +46,7 @@ export function parseFrontmatter(content: string): Frontmatter {
   }
 
   if (inArray && currentKey) result[currentKey] = arrayValues.slice();
-  return result;
+  return validateFrontmatter(result);
 }
 
 export function collectMarkdownFiles(dir: string): string[] {