genesis-compiler 1.10.4 → 1.10.5

package/README.md

@@ -941,6 +941,7 @@ import {
   syncSkills,
   validateArchitectureFacts,
   validateArchitectureObservations,
+  validateCityDocument,
   verify,
   withTrustedGitRepository,
 } from 'genesis-compiler';
@@ -991,6 +992,12 @@ and packages; `connectArchitectureObservations()` joins exact owners and
 controller operations. `mergeArchitectureObservations()` combines distinct
 inspectors while rejecting conflicting facts or package snapshots.
 `validateArchitectureFacts()` validates the combined architecture snapshot.
+`validateCityDocument(city, kind)` validates a saved or freshly built Machine
+(`'machine'`) or Program (`'program'`) City document against the format Genesis
+writes, including embedded architecture facts, and returns it unchanged; hosts
+reading `.genesis/*-city.json` call it rather than keeping their own copy.
+`MACHINE_CITY_SCHEMA`, `PROGRAM_CITY_SCHEMA` and `CITY_SCHEMA_VERSION` name
+those formats.
 These operations neither run a framework inspector nor claim complete runtime
 behavior.
 `sourceExplanationGuidance()` and `sourceExplanationReviewGuidance()` supply

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.10.4",
+  "version": "1.10.5",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with project agent guidance.",
   "repository": {

package/plugins/genesis/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis",
-  "version": "1.10.4",
+  "version": "1.10.5",
   "description": "Makes Codex aware of optional Genesis adoption for existing projects.",
   "author": {
     "name": "Mobily Enterprises"

package/src/index/city-documents.js

@@ -0,0 +1,148 @@
+import { GenesisError } from './errors.js';
+import { validateArchitectureFacts } from './architecture.js';
+
+// The Machine and Program City document formats are produced here
+// (code-index.js), so their shape and validation are owned here too. A host
+// reading a saved City calls validateCityDocument instead of keeping a copy.
+export const MACHINE_CITY_SCHEMA = 'genesis.machine-city.v1';
+export const PROGRAM_CITY_SCHEMA = 'genesis.program-city.v1';
+export const CITY_SCHEMA_VERSION = 1;
+
+const CITY_KINDS = Object.freeze({
+  machine: Object.freeze({ schema: MACHINE_CITY_SCHEMA, title: 'Machine City' }),
+  program: Object.freeze({ schema: PROGRAM_CITY_SCHEMA, title: 'Program City' }),
+});
+
+function checker(kind) {
+  const title = CITY_KINDS[kind].title;
+  const check = (condition, message) => {
+    if (!condition) throw new GenesisError('CITY_INVALID', `${title} ${message}`, { kind });
+  };
+  const record = (value, label) => check(value !== null && typeof value === 'object' && !Array.isArray(value), `${label} must be an object.`);
+  const array = (value, label) => check(Array.isArray(value), `${label} must be an array.`);
+  const string = (value, label) => check(typeof value === 'string', `${label} must be a string.`);
+  const optionalString = (value, label) => check(value === null || typeof value === 'string', `${label} must be a string or null.`);
+  const boolean = (value, label) => check(typeof value === 'boolean', `${label} must be a boolean.`);
+  const count = (value, label) => check(Number.isInteger(value) && value >= 0, `${label} must be a non-negative integer.`);
+  const strings = (value, label) => {
+    array(value, label);
+    value.forEach((entry, index) => string(entry, `${label}[${index}]`));
+  };
+  const diagnostics = (value) => {
+    array(value, 'diagnostics');
+    value.forEach((entry, index) => record(entry, `diagnostics[${index}]`));
+  };
+  const uniqueIds = (records, label) => {
+    const seen = new Set();
+    records.forEach((entry, index) => {
+      record(entry, `${label}[${index}]`);
+      string(entry.id, `${label}[${index}].id`);
+      check(!seen.has(entry.id), `${label} contains duplicate id ${entry.id}.`);
+      seen.add(entry.id);
+    });
+    return seen;
+  };
+  const districts = (value) => {
+    array(value, 'districts');
+    const ids = uniqueIds(value, 'districts');
+    value.forEach((district, index) => {
+      const label = `districts[${index}]`;
+      string(district.path, `${label}.path`);
+      string(district.title, `${label}.title`);
+      optionalString(district.parentId, `${label}.parentId`);
+      if (district.parentId !== null) check(ids.has(district.parentId), `${label}.parentId does not identify a district.`);
+    });
+    return ids;
+  };
+  return { array, boolean, check, count, diagnostics, districts, optionalString, record, string, strings, uniqueIds };
+}
+
+function validateMachineCity(city) {
+  const v = checker('machine');
+  v.string(city.codeHash, 'codeHash');
+  v.strings(city.stackComponents, 'stackComponents');
+  v.strings(city.indexers, 'indexers');
+  v.diagnostics(city.diagnostics);
+  const districtIds = v.districts(city.districts);
+
+  v.array(city.buildings, 'buildings');
+  const buildingIds = v.uniqueIds(city.buildings, 'buildings');
+  city.buildings.forEach((building, index) => {
+    const label = `buildings[${index}]`;
+    for (const field of ['path', 'title', 'districtId', 'language', 'role', 'hash']) v.string(building[field], `${label}.${field}`);
+    v.check(districtIds.has(building.districtId), `${label}.districtId does not identify a district.`);
+    for (const field of ['mode', 'bytes', 'lines']) v.count(building[field], `${label}.${field}`);
+    v.strings(building.extractors, `${label}.extractors`);
+    v.strings(building.functionIds, `${label}.functionIds`);
+    v.count(building.publicFunctionCount, `${label}.publicFunctionCount`);
+    v.count(building.internalFunctionCount, `${label}.internalFunctionCount`);
+  });
+
+  v.array(city.functions, 'functions');
+  const functionIds = v.uniqueIds(city.functions, 'functions');
+  city.functions.forEach((entry, index) => {
+    const label = `functions[${index}]`;
+    for (const field of ['name', 'qualifiedName', 'kind', 'visibility', 'path', 'fileId', 'role', 'language', 'extractor']) {
+      v.string(entry[field], `${label}.${field}`);
+    }
+    v.optionalString(entry.container, `${label}.container`);
+    v.check(buildingIds.has(entry.fileId), `${label}.fileId does not identify a building.`);
+    v.count(entry.line, `${label}.line`);
+    v.count(entry.column, `${label}.column`);
+    v.strings(entry.parameters, `${label}.parameters`);
+    for (const field of ['async', 'generator', 'static']) v.boolean(entry[field], `${label}.${field}`);
+  });
+  city.buildings.forEach((building, index) => {
+    for (const functionId of building.functionIds) {
+      v.check(functionIds.has(functionId), `buildings[${index}].functionIds contains an unknown function id.`);
+    }
+  });
+  if (city.architecture) validateArchitectureFacts(city.architecture);
+}
+
+function validateProgramCity(city) {
+  const v = checker('program');
+  v.string(city.programHash, 'programHash');
+  v.diagnostics(city.diagnostics);
+  const districtIds = v.districts(city.districts);
+
+  v.array(city.buildings, 'buildings');
+  const buildingIds = v.uniqueIds(city.buildings, 'buildings');
+  city.buildings.forEach((building, index) => {
+    const label = `buildings[${index}]`;
+    for (const field of ['name', 'title', 'description', 'publicContract', 'implementationMap', 'path']) v.string(building[field], `${label}.${field}`);
+    v.optionalString(building.subsystem, `${label}.subsystem`);
+    v.optionalString(building.districtId, `${label}.districtId`);
+    v.check(building.districtId === null || districtIds.has(building.districtId), `${label}.districtId does not identify a district.`);
+    v.strings(building.sources, `${label}.sources`);
+    if (building.mainSource !== undefined) {
+      v.string(building.mainSource, `${label}.mainSource`);
+      v.check(building.sources.includes(building.mainSource), `${label}.mainSource must be a cited source.`);
+    }
+    v.strings(building.sourceFileIds, `${label}.sourceFileIds`);
+  });
+
+  v.array(city.links, 'links');
+  city.links.forEach((link, index) => {
+    const label = `links[${index}]`;
+    v.record(link, label);
+    v.check(link.kind === 'implemented-by', `${label}.kind must be implemented-by.`);
+    v.string(link.fromId, `${label}.fromId`);
+    v.string(link.toId, `${label}.toId`);
+    v.check(buildingIds.has(link.fromId), `${label}.fromId does not identify a Program building.`);
+  });
+}
+
+// Validates a saved or freshly built City document of the given kind
+// ('machine' or 'program') and returns it unchanged.
+export function validateCityDocument(city, kind) {
+  if (!Object.hasOwn(CITY_KINDS, kind)) throw new GenesisError('CITY_KIND_UNSUPPORTED', `City kind is not supported: ${String(kind || '')}`);
+  const v = checker(kind);
+  v.record(city, 'document');
+  v.check(city.schema === CITY_KINDS[kind].schema, `schema must be ${CITY_KINDS[kind].schema}.`);
+  v.check(city.schemaVersion === CITY_SCHEMA_VERSION, `schemaVersion must be ${CITY_SCHEMA_VERSION}.`);
+  v.string(city.status, 'status');
+  if (kind === 'machine') validateMachineCity(city);
+  else validateProgramCity(city);
+  return city;
+}

package/src/index/code-index.js

@@ -11,6 +11,7 @@ import { isProjectContentPath } from './paths.js';
 import { inspectProgram } from './program.js';
 import { inspectSubsystems } from './subsystems.js';
 import { buildArchitectureFacts } from './architecture.js';
+import { CITY_SCHEMA_VERSION, MACHINE_CITY_SCHEMA, PROGRAM_CITY_SCHEMA } from './city-documents.js';
 import { gitVisibleFileStates } from './project-files.js';
 import { readStack } from './stack.js';
 import { sha256, stableJson, writeFileAtomic } from './utils.js';
@@ -162,8 +163,8 @@ function machineCity({ cityRegions, components, contributions, diagnostics, inde
     mode,
   }))));
   return {
-    schema: 'genesis.machine-city.v1',
-    schemaVersion: 1,
+    schema: MACHINE_CITY_SCHEMA,
+    schemaVersion: CITY_SCHEMA_VERSION,
     status: indexers.length === 0 ? 'unconfigured' : diagnostics.length > 0 ? 'completed-with-warning' : 'current',
     codeHash,
     presentationRegions: presentation.regions,
@@ -206,8 +207,8 @@ async function programCity(projectRoot) {
       sourceFileIds: module.sources.map(fileId),
     }));
     return {
-      schema: 'genesis.program-city.v1',
-      schemaVersion: 1,
+      schema: PROGRAM_CITY_SCHEMA,
+      schemaVersion: CITY_SCHEMA_VERSION,
       status: program.status,
       programHash: sha256(stableJson({ operations, subsystems: program.subsystemMap })),
       diagnostics: [],
@@ -221,8 +222,8 @@ async function programCity(projectRoot) {
     };
   } catch (error) {
     return {
-      schema: 'genesis.program-city.v1',
-      schemaVersion: 1,
+      schema: PROGRAM_CITY_SCHEMA,
+      schemaVersion: CITY_SCHEMA_VERSION,
       status: 'invalid',
       programHash: sha256('invalid'),
       diagnostics: [asDiagnostic(error)],

package/src/index.js

@@ -248,3 +248,4 @@ export { inspectOpenCodePlugin, installOpenCodePlugin as syncOpenCodePlugin } fr
 export { ARCHITECTURE_OBSERVATIONS_SCHEMA, validateArchitectureObservations, connectArchitectureObservations, mergeArchitectureObservations } from './index/architecture-observations.js';
 
 export { validateArchitectureFacts } from './index/architecture.js';
+export { CITY_SCHEMA_VERSION, MACHINE_CITY_SCHEMA, PROGRAM_CITY_SCHEMA, validateCityDocument } from './index/city-documents.js';