glossarist 0.1.7 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glossarist",
-  "version": "0.1.7",
+  "version": "0.2.1",
   "description": "JavaScript SDK for Glossarist GCR packages — read, write, validate, and manage terminology concepts",
   "type": "module",
   "main": "src/index.js",

package/src/concept-collection.js

@@ -1,4 +1,4 @@
-import { naturalSort } from './gcr-reader.js';
+import { naturalSort } from './sort.js';
 
 const _items = Symbol('items');
 
@@ -37,8 +37,7 @@ export class ConceptCollection {
 
   byStatus(status) {
     return new ConceptCollection(this[_items].filter(c => {
-      const langs = c.languages;
-      return langs.length > 0 && c.localization(langs[0])?.entryStatus === status;
+      return c.languages.some(lang => c.localization(lang)?.entryStatus === status);
     }));
   }
 

package/src/concept-reader.d.ts

@@ -1,4 +1,4 @@
-import type { Concept } from './gcr-reader';
+import type { Concept } from './models/index';
 
 /** Read all concept YAML files from a directory. */
 export function readConcepts(dir: string): Concept[];

package/src/concept-reader.js

@@ -2,7 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import yaml from 'js-yaml';
 import { conceptParser } from './concept-parser.js';
-import { naturalSort } from './gcr-reader.js';
+import { naturalSort } from './sort.js';
 import { InvalidInputError } from './errors.js';
 
 function assertDir(dir, fnName) {

package/src/gcr-reader.d.ts

@@ -1,52 +1,4 @@
-/** A single term designation. */
-export interface Term {
-  type: string;
-  designation: string;
-  normative_status?: string;
-}
-
-/** A definition content block. */
-export interface Definition {
-  content: string;
-}
-
-/** A bibliographic source reference. */
-export interface Source {
-  type: string;
-  origin?: { ref: string };
-}
-
-/** Localized concept data for a single language. */
-export interface Localization {
-  terms: Term[];
-  definition?: Definition[];
-  notes?: { content: string }[];
-  examples?: { content: string }[];
-  sources?: Source[];
-  entry_status?: string;
-  normative_status?: string;
-}
-
-/** A normalized glossarist concept. */
-export interface Concept {
-  termid: string;
-  term: string | null;
-  localizations: Record<string, Localization>;
-  raw: Record<string, unknown>;
-}
-
-/** GCR package metadata from metadata.yaml. */
-export interface GcrMetadata {
-  shortname: string;
-  version?: string;
-  title?: string;
-  concept_count?: number;
-  languages?: string[];
-  schema_version?: string;
-  glossarist_version?: string;
-  created_at?: string;
-  statistics?: Record<string, unknown>;
-}
+import { Concept, GcrMetadata } from './models/index';
 
 /**
  * Load a GCR package from a ZIP archive.
@@ -56,7 +8,7 @@ export function loadGcr(input: Buffer | ArrayBuffer | Uint8Array | Blob | string
 
 /** A loaded GCR package (ZIP archive of glossarist concept data). */
 export class GcrPackage {
-  /** Read and parse metadata.yaml. */
+  /** Read and parse metadata.yaml as a GcrMetadata instance. */
   metadata(): Promise<GcrMetadata | null>;
   /** Read and parse optional register.yaml. */
   register(): Promise<Record<string, unknown> | null>;
@@ -88,6 +40,10 @@ export class GcrPackage {
 
   // Dataset assets (bibliography, images)
 
+  /** List all dataset asset entries found in this package. */
+  datasetAssetEntries(): Promise<Array<{ path: string; type: 'file' | 'directory'; asset: { path: string; type: string } }>>;
+  /** Read a file-type dataset asset by its registered path. */
+  readDatasetFileAsset(assetPath: string): Promise<string | null>;
   /** Read bibliography.yaml from the package as raw YAML string. */
   bibliography(): Promise<string | null>;
   /** Check whether the images/ directory is present and non-empty. */
@@ -102,7 +58,7 @@ export class GcrPackage {
   allImageFiles(): Promise<Map<string, Uint8Array>>;
 }
 
-/** Parse raw concept YAML (canonical or managed format) into a normalized Concept. */
+/** Parse raw concept YAML (canonical or managed format) into a Concept. */
 export function parseConceptYaml(raw: string, context?: string): Concept;
 
 /** Natural sort comparator for concept IDs like "3.1.1.1", "551-12-39". */

package/src/gcr-reader.js

@@ -3,11 +3,13 @@ import yaml from 'js-yaml';
 import { conceptParser } from './concept-parser.js';
 import { InvalidInputError } from './errors.js';
 import { COMPILED_FORMATS, parseCompiledPath, compiledPath } from './compiled-format.js';
+import { DATASET_ASSETS, findFileAsset, findDirectoryAssetPath } from './dataset-asset.js';
+import { GcrMetadata } from './models/gcr-metadata.js';
+import { naturalSort } from './sort.js';
 
-const BASE64_RE = /^[A-Za-z0-9+/]{100,}={0,2}$/;
+export { naturalSort } from './sort.js';
 
-const NATURAL_SORT_RE = /(\d+|\D+)/g;
-const DIGIT_RE = /^\d+$/;
+const BASE64_RE = /^[A-Za-z0-9+/]{100,}={0,2}$/;
 
 /**
  * @typedef {Object} Term
@@ -81,12 +83,12 @@ export class GcrPackage {
   }
 
   /**
-   * Read and parse metadata.yaml from the package.
+   * Read and parse metadata.yaml from the package as a GcrMetadata instance.
    * @returns {Promise<GcrMetadata | null>}
    */
   async metadata() {
     const raw = await this._readText('metadata.yaml');
-    return raw ? yaml.load(raw) : null;
+    return raw ? GcrMetadata.fromYaml(raw) : null;
   }
 
   /**
@@ -249,22 +251,58 @@ export class GcrPackage {
 
   // --- Dataset assets (bibliography, images, etc.) ---
 
+  /**
+   * List all dataset asset entries found in this package.
+   * Each entry has { path, type, asset } where asset is the registry descriptor.
+   * @returns {Promise<Array<{ path: string, type: 'file' | 'directory', asset: { path: string, type: string } }>>}
+   */
+  async datasetAssetEntries() {
+    const entries = [];
+    this._zip.forEach((relativePath, zipEntry) => {
+      if (zipEntry.dir) return;
+      const fileAsset = findFileAsset(relativePath);
+      if (fileAsset) {
+        entries.push({ path: relativePath, type: 'file', asset: fileAsset });
+        return;
+      }
+      const dirAsset = findDirectoryAssetPath(relativePath);
+      if (dirAsset) {
+        entries.push({ path: relativePath, type: 'directory', asset: dirAsset });
+      }
+    });
+    return entries;
+  }
+
+  /**
+   * Read a file-type dataset asset by its registered path (e.g. 'bibliography.yaml').
+   * @param {string} assetPath - registered file asset path
+   * @returns {Promise<string | null>}
+   */
+  async readDatasetFileAsset(assetPath) {
+    return this._readText(assetPath);
+  }
+
   /**
    * Read bibliography.yaml from the package as a string (raw YAML).
    * @returns {Promise<string | null>}
    */
   async bibliography() {
-    return this._readText('bibliography.yaml');
+    const fileAsset = DATASET_ASSETS.find((a) => a.type === 'file' && a.path === 'bibliography.yaml');
+    return fileAsset ? this._readText(fileAsset.path) : null;
   }
 
   /**
    * Check whether the images/ directory is present and non-empty.
+   * Uses the dataset-asset registry to find the images directory.
    * @returns {Promise<boolean>}
    */
   async hasImages() {
+    const asset = DATASET_ASSETS.find((a) => a.type === 'directory' && a.path === 'images');
+    if (!asset) return false;
+    const prefix = `${asset.path}/`;
     let found = false;
     this._zip.forEach((relativePath, entry) => {
-      if (!found && !entry.dir && relativePath.startsWith('images/')) {
+      if (!found && !entry.dir && relativePath.startsWith(prefix)) {
         found = true;
       }
     });
@@ -273,12 +311,16 @@ export class GcrPackage {
 
   /**
    * List all image file paths (relative to ZIP root).
+   * Uses the dataset-asset registry to find the images directory.
    * @returns {Promise<string[]>}
    */
   async imageFileNames() {
+    const asset = DATASET_ASSETS.find((a) => a.type === 'directory' && a.path === 'images');
+    if (!asset) return [];
+    const prefix = `${asset.path}/`;
     const names = [];
     this._zip.forEach((relativePath, entry) => {
-      if (!entry.dir && relativePath.startsWith('images/')) {
+      if (!entry.dir && relativePath.startsWith(prefix)) {
         names.push(relativePath);
       }
     });
@@ -291,7 +333,9 @@ export class GcrPackage {
    * @returns {Promise<Uint8Array | null>}
    */
   async imageFile(path) {
-    const fullPath = path.startsWith('images/') ? path : `images/${path}`;
+    const asset = DATASET_ASSETS.find((a) => a.type === 'directory' && a.path === 'images');
+    if (!asset) return null;
+    const fullPath = path.startsWith(`${asset.path}/`) ? path : `${asset.path}/${path}`;
     const entry = this._zip.file(fullPath);
     if (!entry) return null;
     return entry.async('uint8array');
@@ -350,34 +394,6 @@ export function parseConceptYaml(raw, context) {
   return conceptParser.parse(raw, context);
 }
 
-// --- Helpers ---
-
-/**
- * Natural sort comparator for concept IDs like "3.1.1.1", "551-12-39".
- * @param {string} a
- * @param {string} b
- * @returns {number}
- *
- * @example
- * ['3.1.10', '3.1.2', '3.1.1'].sort(naturalSort); // ['3.1.1', '3.1.2', '3.1.10']
- */
-export function naturalSort(a, b) {
-  const pa = a.match(NATURAL_SORT_RE) || [];
-  const pb = b.match(NATURAL_SORT_RE) || [];
-  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-    const na = pa[i] || '';
-    const nb = pb[i] || '';
-    if (DIGIT_RE.test(na) && DIGIT_RE.test(nb)) {
-      const diff = parseInt(na, 10) - parseInt(nb, 10);
-      if (diff !== 0) return diff;
-    } else {
-      const cmp = na.localeCompare(nb);
-      if (cmp !== 0) return cmp;
-    }
-  }
-  return 0;
-}
-
 /**
  * @typedef {Object} GcrMetadata
  * @property {string} shortname - dataset short name

package/src/gcr-writer.d.ts

@@ -1,4 +1,4 @@
-import { Concept } from './models/index';
+import { Concept, GcrMetadata } from './models/index';
 
 /** Compiled formats map: format name → id → content string. */
 export type CompiledFormatsMap = Record<string, Record<string, string> | Map<string, string>>;
@@ -9,7 +9,7 @@ export type ImagesMap = Record<string, Uint8Array | string | ArrayBuffer> | Map<
 export class GcrWriter {
   static createBuffer(options: {
     concepts: Concept[];
-    metadata?: Record<string, unknown>;
+    metadata?: GcrMetadata | Record<string, unknown>;
     register?: Record<string, unknown>;
     uuidFn?: () => string;
     format?: 'canonical' | 'managed' | 'auto';

package/src/gcr-writer.js

@@ -2,6 +2,8 @@ import JSZip from 'jszip';
 import { conceptSerializer } from './concept-serializer.js';
 import { InvalidInputError } from './errors.js';
 import { compiledPath, isKnownFormat } from './compiled-format.js';
+import { GcrMetadata } from './models/gcr-metadata.js';
+import { GcrStatistics } from './models/gcr-statistics.js';
 
 export class GcrWriter {
   static async createBuffer(options) {
@@ -15,7 +17,8 @@ export class GcrWriter {
     const zip = new JSZip();
 
     if (options.metadata) {
-      zip.file('metadata.yaml', conceptSerializer.toRegisterYaml(options.metadata));
+      const meta = GcrWriter._normalizeMetadata(options.metadata, options.concepts);
+      zip.file('metadata.yaml', conceptSerializer.toRegisterYaml(meta));
     }
     if (options.register) {
       zip.file('register.yaml', conceptSerializer.toRegisterYaml(options.register));
@@ -45,6 +48,26 @@ export class GcrWriter {
     return zip.generateAsync({ type: 'uint8array' });
   }
 
+  static _normalizeMetadata(metadata, concepts) {
+    if (metadata instanceof GcrMetadata) {
+      const meta = metadata.clone();
+      if (!meta.statistics && concepts.length > 0) {
+        meta.statistics = GcrStatistics.fromConcepts(concepts);
+      }
+      if (!meta.conceptCount) meta.conceptCount = concepts.length;
+      return meta.toJSON();
+    }
+
+    const data = { ...metadata };
+    if (!data.statistics && concepts.length > 0) {
+      data.statistics = GcrStatistics.fromConcepts(concepts).toJSON();
+    }
+    if (!data.concept_count && concepts.length > 0) {
+      data.concept_count = concepts.length;
+    }
+    return data;
+  }
+
   static _writeCompiledFormats(zip, compiledFormats) {
     for (const [format, entries] of Object.entries(compiledFormats)) {
       if (!isKnownFormat(format)) {

package/src/index.d.ts

@@ -5,12 +5,12 @@ export {
   Designation, Expression, Abbreviation, Symbol, GraphicalSymbol,
   Citation, ConceptSource, RelatedConcept, ConceptDate,
   DetailedDefinition, NonVerbRep,
+  GcrMetadata, GcrStatistics,
   RELATIONSHIP_TYPES, DATE_TYPES,
 } from './models/index';
 
 // GCR reader
 export { loadGcr, GcrPackage, parseConceptYaml, naturalSort } from './gcr-reader';
-export type { GcrMetadata } from './gcr-reader';
 
 // GCR writer
 export { createGcr, GcrWriter } from './gcr-writer';
@@ -26,7 +26,7 @@ export { ConceptCollection } from './concept-collection';
 export { ManagedConceptCollection } from './managed-concept-collection';
 
 // Validators
-export { validateConcept, validateRegister, createConceptValidator, ValidationError, ValidationRule, RegisterValidator } from './validators/index';
+export { validateConcept, validateRegister, validateGcrPackage, createConceptValidator, ValidationError, ValidationRule, ValidationResult, RegisterValidator, GcrValidator } from './validators/index';
 
 // UUID
 export { conceptUuid, localizedConceptUuid, uuidV5 } from './uuid';
@@ -52,3 +52,6 @@ export function parseCompiledPath(zipPath: string): { format: string; id: string
 export const DATASET_ASSETS: readonly { path: string; type: string }[];
 export const FILE_ASSETS: readonly { path: string; type: string }[];
 export const DIRECTORY_ASSETS: readonly { path: string; type: string }[];
+export function findFileAsset(path: string): { path: string; type: string } | undefined;
+export function findDirectoryAssetPath(zipPath: string): { path: string; type: string } | undefined;
+export function isDatasetAssetPath(zipPath: string): boolean;

package/src/index.js

@@ -1,10 +1,11 @@
-export { loadGcr, GcrPackage, parseConceptYaml, naturalSort } from './gcr-reader.js';
+export { naturalSort } from './sort.js';
+export { loadGcr, GcrPackage, parseConceptYaml } from './gcr-reader.js';
 export { readConcepts, readConcept, listConceptIds, readRegister } from './concept-reader.js';
 export { writeConcept, writeConcepts } from './concept-writer.js';
 export { createGcr, GcrWriter } from './gcr-writer.js';
 export { ConceptCollection } from './concept-collection.js';
 export { ManagedConceptCollection } from './managed-concept-collection.js';
-export { validateConcept, validateRegister, createConceptValidator, ValidationError, ValidationRule, RegisterValidator } from './validators/index.js';
+export { validateConcept, validateRegister, validateGcrPackage, createConceptValidator, ValidationError, ValidationRule, ValidationResult, RegisterValidator, GcrValidator } from './validators/index.js';
 export { conceptUuid, localizedConceptUuid, uuidV5 } from './uuid.js';
 export { ReferenceResolver, Reference, referenceResolver } from './reference-resolver.js';
 export { V1Reader, migrateV1ToV2 } from './v1-reader.js';
@@ -31,5 +32,6 @@ export {
   Designation, Expression, Abbreviation, Symbol, GraphicalSymbol,
   Citation, ConceptSource, RelatedConcept, ConceptDate,
   DetailedDefinition, NonVerbRep,
+  GcrMetadata, GcrStatistics,
   RELATIONSHIP_TYPES, DATE_TYPES,
 } from './models/index.js';

package/src/models/gcr-metadata.js

@@ -0,0 +1,68 @@
+import yaml from 'js-yaml';
+import { GlossaristModel } from './base.js';
+import { GcrStatistics } from './gcr-statistics.js';
+
+export class GcrMetadata extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    this.shortname = data.shortname ?? null;
+    this.version = data.version ?? null;
+    this.title = data.title ?? null;
+    this.description = data.description ?? null;
+    this.owner = data.owner ?? null;
+    this.tags = data.tags ?? [];
+    this.conceptCount = data.concept_count ?? data.conceptCount ?? 0;
+    this.languages = data.languages ?? [];
+    this.createdAt = data.created_at ?? data.createdAt ?? null;
+    this.glossaristVersion = data.glossarist_version ?? data.glossaristVersion ?? null;
+    this.schemaVersion = data.schema_version ?? data.schemaVersion ?? '1';
+    this.homepage = data.homepage ?? null;
+    this.repository = data.repository ?? null;
+    this.license = data.license ?? null;
+    this.uriPrefix = data.uri_prefix ?? data.uriPrefix ?? null;
+    this.conceptUriTemplate = data.concept_uri_template ?? data.conceptUriTemplate ?? null;
+    this.compiledFormats = data.compiled_formats ?? data.compiledFormats ?? [];
+    this.statistics = data.statistics
+      ? (data.statistics instanceof GcrStatistics ? data.statistics : new GcrStatistics(data.statistics))
+      : null;
+  }
+
+  get concept_count() { return this.conceptCount; }
+  get created_at() { return this.createdAt; }
+  get glossarist_version() { return this.glossaristVersion; }
+  get schema_version() { return this.schemaVersion; }
+  get uri_prefix() { return this.uriPrefix; }
+  get concept_uri_template() { return this.conceptUriTemplate; }
+  get compiled_formats() { return this.compiledFormats; }
+
+  toJSON() {
+    const obj = {};
+    if (this.shortname != null) obj.shortname = this.shortname;
+    if (this.version != null) obj.version = this.version;
+    if (this.title != null) obj.title = this.title;
+    if (this.description != null) obj.description = this.description;
+    if (this.owner != null) obj.owner = this.owner;
+    if (this.tags.length > 0) obj.tags = this.tags;
+    if (this.conceptCount > 0) obj.concept_count = this.conceptCount;
+    if (this.languages.length > 0) obj.languages = this.languages;
+    if (this.createdAt != null) obj.created_at = this.createdAt;
+    if (this.glossaristVersion != null) obj.glossarist_version = this.glossaristVersion;
+    if (this.schemaVersion != null) obj.schema_version = this.schemaVersion;
+    if (this.homepage != null) obj.homepage = this.homepage;
+    if (this.repository != null) obj.repository = this.repository;
+    if (this.license != null) obj.license = this.license;
+    if (this.uriPrefix != null) obj.uri_prefix = this.uriPrefix;
+    if (this.conceptUriTemplate != null) obj.concept_uri_template = this.conceptUriTemplate;
+    if (this.compiledFormats.length > 0) obj.compiled_formats = this.compiledFormats;
+    if (this.statistics != null) obj.statistics = this.statistics.toJSON();
+    return obj;
+  }
+
+  static fromJSON(data) {
+    return new GcrMetadata(data);
+  }
+
+  static fromYaml(yamlString) {
+    return new GcrMetadata(yaml.load(yamlString));
+  }
+}

package/src/models/gcr-statistics.js

@@ -0,0 +1,51 @@
+import { GlossaristModel } from './base.js';
+
+export class GcrStatistics extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    this.totalConcepts = data.total_concepts ?? data.totalConcepts ?? 0;
+    this.conceptsWithDefinitions = data.concepts_with_definitions ?? data.conceptsWithDefinitions ?? 0;
+    this.conceptsByStatus = data.concepts_by_status ?? data.conceptsByStatus ?? {};
+  }
+
+  get total_concepts() { return this.totalConcepts; }
+  get concepts_with_definitions() { return this.conceptsWithDefinitions; }
+  get concepts_by_status() { return this.conceptsByStatus; }
+
+  toJSON() {
+    const obj = { total_concepts: this.totalConcepts };
+    if (this.conceptsWithDefinitions > 0) {
+      obj.concepts_with_definitions = this.conceptsWithDefinitions;
+    }
+    if (Object.keys(this.conceptsByStatus).length > 0) {
+      obj.concepts_by_status = this.conceptsByStatus;
+    }
+    return obj;
+  }
+
+  static fromJSON(data) {
+    return new GcrStatistics(data);
+  }
+
+  static fromConcepts(concepts) {
+    const langs = new Set();
+    let withDefs = 0;
+    const byStatus = {};
+
+    for (const concept of concepts) {
+      for (const lang of concept.languages) {
+        langs.add(lang);
+        const lc = concept.localization(lang);
+        if (lc && lc.definitions.length > 0) withDefs++;
+        const status = lc?.entryStatus ?? 'unknown';
+        byStatus[status] = (byStatus[status] ?? 0) + 1;
+      }
+    }
+
+    return new GcrStatistics({
+      total_concepts: concepts.length,
+      concepts_with_definitions: withDefs,
+      concepts_by_status: byStatus,
+    });
+  }
+}

package/src/models/index.d.ts

@@ -106,3 +106,42 @@ export class NonVerbRep extends GlossaristModel {
   readonly formula: string | null;
   readonly sources: Citation[];
 }
+
+export class GcrStatistics extends GlossaristModel {
+  readonly totalConcepts: number;
+  readonly conceptsWithDefinitions: number;
+  readonly conceptsByStatus: Record<string, number>;
+  readonly total_concepts: number;
+  readonly concepts_with_definitions: number;
+  readonly concepts_by_status: Record<string, number>;
+  static fromConcepts(concepts: Concept[]): GcrStatistics;
+  static fromJSON(data: Record<string, unknown>): GcrStatistics;
+}
+
+export class GcrMetadata extends GlossaristModel {
+  readonly shortname: string | null;
+  readonly version: string | null;
+  readonly title: string | null;
+  readonly description: string | null;
+  readonly owner: string | null;
+  readonly tags: string[];
+  readonly conceptCount: number;
+  readonly languages: string[];
+  readonly createdAt: string | null;
+  readonly glossaristVersion: string | null;
+  readonly schemaVersion: string;
+  readonly homepage: string | null;
+  readonly repository: string | null;
+  readonly license: string | null;
+  readonly uriPrefix: string | null;
+  readonly conceptUriTemplate: string | null;
+  readonly compiledFormats: string[];
+  readonly statistics: GcrStatistics | null;
+  readonly concept_count: number;
+  readonly created_at: string | null;
+  readonly glossarist_version: string | null;
+  readonly schema_version: string;
+  readonly compiled_formats: string[];
+  static fromYaml(yamlString: string): GcrMetadata;
+  static fromJSON(data: Record<string, unknown>): GcrMetadata;
+}

package/src/models/index.js

@@ -8,3 +8,5 @@ export { RelatedConcept, RELATIONSHIP_TYPES } from './related-concept.js';
 export { ConceptDate, DATE_TYPES } from './concept-date.js';
 export { DetailedDefinition } from './detailed-definition.js';
 export { NonVerbRep } from './non-verb-rep.js';
+export { GcrMetadata } from './gcr-metadata.js';
+export { GcrStatistics } from './gcr-statistics.js';;

package/src/sort.js

@@ -0,0 +1,25 @@
+const NATURAL_SORT_RE = /(\d+|\D+)/g;
+const DIGIT_RE = /^\d+$/;
+
+/**
+ * Natural sort comparator for concept IDs like "3.1.1.1", "551-12-39".
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export function naturalSort(a, b) {
+  const pa = a.match(NATURAL_SORT_RE) || [];
+  const pb = b.match(NATURAL_SORT_RE) || [];
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const na = pa[i] || '';
+    const nb = pb[i] || '';
+    if (DIGIT_RE.test(na) && DIGIT_RE.test(nb)) {
+      const diff = parseInt(na, 10) - parseInt(nb, 10);
+      if (diff !== 0) return diff;
+    } else {
+      const cmp = na.localeCompare(nb);
+      if (cmp !== 0) return cmp;
+    }
+  }
+  return 0;
+}

package/src/validators/gcr-validator.js

@@ -0,0 +1,74 @@
+import yaml from 'js-yaml';
+import { DATASET_ASSETS } from '../dataset-asset.js';
+import { ValidationResult } from './validation-result.js';
+
+export class GcrValidator {
+  async validate(pkg) {
+    const result = new ValidationResult();
+    await this._validateMetadata(pkg, result);
+    await this._validateConcepts(pkg, result);
+    await this._validateAssets(pkg, result);
+    return result;
+  }
+
+  async _validateMetadata(pkg, result) {
+    const raw = await pkg._readText('metadata.yaml');
+    if (!raw) {
+      result.addError('metadata.yaml is missing');
+      return;
+    }
+
+    let meta;
+    try {
+      meta = yaml.load(raw);
+    } catch (e) {
+      result.addError(`metadata.yaml: invalid YAML: ${e.message}`);
+      return;
+    }
+
+    if (!meta.shortname) result.addError('metadata.yaml missing shortname');
+    if (!meta.version) result.addError('metadata.yaml missing version');
+    if (meta.concept_count == null) result.addError('metadata.yaml missing concept_count');
+  }
+
+  async _validateConcepts(pkg, result) {
+    const ids = await pkg.conceptIds();
+    if (ids.length === 0) {
+      result.addError('No concept files found in concepts/');
+    }
+  }
+
+  async _validateAssets(pkg, result) {
+    for (const asset of DATASET_ASSETS) {
+      if (asset.type === 'file') {
+        await this._validateFileAsset(pkg, asset.path, result);
+      } else if (asset.type === 'directory') {
+        await this._validateDirectoryAsset(pkg, asset.path, result);
+      }
+    }
+  }
+
+  async _validateFileAsset(pkg, path, result) {
+    const raw = await pkg._readText(path);
+    if (!raw) return;
+    try {
+      yaml.load(raw);
+    } catch (e) {
+      result.addError(`${path}: invalid YAML at line ${e.mark?.line ?? '?'}: ${e.message}`);
+    }
+  }
+
+  async _validateDirectoryAsset(pkg, dirPath, result) {
+    let hasFiles = false;
+    let hasEntries = false;
+    pkg._zip.forEach((relativePath, entry) => {
+      if (relativePath.startsWith(`${dirPath}/`)) {
+        hasEntries = true;
+        if (!entry.dir) hasFiles = true;
+      }
+    });
+    if (hasEntries && !hasFiles) {
+      result.addWarning(`${dirPath}/ directory exists but is empty`);
+    }
+  }
+}

package/src/validators/index.js

@@ -1,10 +1,13 @@
 export { ValidationError } from './validation-error.js';
 export { ValidationRule } from './validation-rule.js';
+export { ValidationResult } from './validation-result.js';
 export { ConceptValidator, LanguageCodeRule, DesignationTypeRule, EntryStatusRule } from './concept-validator.js';
 export { RegisterValidator } from './register-validator.js';
+export { GcrValidator } from './gcr-validator.js';
 
 import { ConceptValidator, LanguageCodeRule, DesignationTypeRule, EntryStatusRule } from './concept-validator.js';
 import { RegisterValidator } from './register-validator.js';
+import { GcrValidator } from './gcr-validator.js';
 
 const _default = new ConceptValidator()
   .addRule(new LanguageCodeRule())
@@ -22,3 +25,7 @@ export function createConceptValidator() {
 export function validateRegister(register) {
   return new RegisterValidator().validate(register);
 }
+
+export async function validateGcrPackage(pkg) {
+  return new GcrValidator().validate(pkg);
+}

package/src/validators/validation-result.js

@@ -0,0 +1,34 @@
+export class ValidationResult {
+  constructor() {
+    this.errors = [];
+    this.warnings = [];
+  }
+
+  get valid() {
+    return this.errors.length === 0;
+  }
+
+  addError(message) {
+    this.errors.push(message);
+    return this;
+  }
+
+  addWarning(message) {
+    this.warnings.push(message);
+    return this;
+  }
+
+  merge(other) {
+    for (const e of other.errors) this.errors.push(e);
+    for (const w of other.warnings) this.warnings.push(w);
+    return this;
+  }
+
+  toJSON() {
+    return {
+      valid: this.valid,
+      errors: [...this.errors],
+      warnings: [...this.warnings],
+    };
+  }
+}