genesis-compiler 1.2.15 → 1.2.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.2.15",
+  "version": "1.2.16",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with optional Codex hooks.",
   "repository": {

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

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

package/src/index/contracts.js

@@ -1,6 +1,6 @@
 export const GENESIS_CONTRACTS = Object.freeze({
   derivedArtifacts: 'genesis.derived-artifacts.v1',
-  environment: 'genesis.environment.v1',
+  environment: 'genesis.environment.v2',
   stackSection: 'genesis.stack-section.v1',
   verification: 'genesis.verification.v1',
 });

package/src/index/stack-piece.js

@@ -7,6 +7,8 @@ import { parseStackVerificationLines } from './stack-verification.js';
 import { normalizeSource } from './utils.js';
 
 const STACK_PIECE_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const RESOURCE_SEMANTIC_PATTERN = /^[a-z][A-Za-z0-9]*$/u;
+const ENVIRONMENT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/u;
 const STACK_CUSTOMIZATION_TITLE = /^# Stack customization: ([a-z0-9]+(?:-[a-z0-9]+)*)\s*$/u;
 const STACK_CUSTOMIZATION_FIELDS = new Map([
   ['Description', 'description'],
@@ -190,6 +192,14 @@ export function parseStackResourceLines(lines, {
     }
     if (
       !resource
+      || typeof resource !== 'object'
+      || Array.isArray(resource)
+      || Object.keys(resource).some((name) => ![
+        'environmentAlternatives',
+        'id',
+        'kind',
+        'optionalBindings',
+      ].includes(name))
       || typeof resource.id !== 'string'
       || !STACK_PIECE_ID_PATTERN.test(resource.id)
       || typeof resource.kind !== 'string'
@@ -199,26 +209,70 @@ export function parseStackResourceLines(lines, {
     ) {
       invalid(resourcePath, 'A Stack resource needs an id, kind, and at least one environment alternative.');
     }
+    const optionalBindings = normalizeResourceBindings(
+      resource.optionalBindings === undefined ? {} : resource.optionalBindings,
+      resourcePath,
+      resource.id,
+      { allowEmpty: true },
+    );
+    const optionalSemantics = new Set(Object.keys(optionalBindings));
     const environmentAlternatives = resource.environmentAlternatives.map((alternative) => {
-      const required = alternative?.required;
-      const allowEmpty = alternative?.allowEmpty || [];
+      if (!alternative || typeof alternative !== 'object' || Array.isArray(alternative)) {
+        invalid(resourcePath, `Stack resource ${resource.id} has an invalid environment alternative.`);
+      }
+      const unknown = Object.keys(alternative).filter((name) => (
+        !['allowEmpty', 'bindings', 'preferred'].includes(name)
+      ));
+      const allowEmpty = alternative.allowEmpty === undefined ? [] : alternative.allowEmpty;
       if (
-        !Array.isArray(required)
+        unknown.length > 0
         || !Array.isArray(allowEmpty)
+        || (alternative.preferred !== undefined && typeof alternative.preferred !== 'boolean')
       ) {
         invalid(resourcePath, `Stack resource ${resource.id} has an invalid environment alternative.`);
       }
-      const names = [...required, ...allowEmpty];
+      const bindings = normalizeResourceBindings(
+        alternative.bindings,
+        resourcePath,
+        resource.id,
+      );
+      const semantics = Object.keys(bindings);
       if (
-        required.length === 0
-        || names.some((name) => typeof name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name))
-        || allowEmpty.some((name) => !required.includes(name))
-        || new Set(required).size !== required.length
+        allowEmpty.some((semantic) => !semantics.includes(semantic))
+        || allowEmpty.some((semantic) => typeof semantic !== 'string')
         || new Set(allowEmpty).size !== allowEmpty.length
-      ) invalid(resourcePath, `Stack resource ${resource.id} has an invalid environment alternative.`);
-      return { required: [...required], allowEmpty: [...allowEmpty] };
+        || semantics.some((semantic) => optionalSemantics.has(semantic))
+        || Object.values(bindings).some((name) => Object.values(optionalBindings).includes(name))
+      ) {
+        invalid(resourcePath, `Stack resource ${resource.id} has an invalid environment alternative.`);
+      }
+      return {
+        allowEmpty: [...allowEmpty].sort(),
+        bindings,
+        preferred: alternative.preferred === true,
+      };
     });
-    return { id: resource.id, kind: resource.kind, environmentAlternatives };
+    if (environmentAlternatives.filter(({ preferred }) => preferred).length !== 1) {
+      invalid(resourcePath, `Stack resource ${resource.id} needs exactly one preferred environment alternative.`);
+    }
+    const semanticByEnvironment = new Map(Object.entries(optionalBindings).map(([semantic, name]) => [
+      name,
+      semantic,
+    ]));
+    for (const alternative of environmentAlternatives) {
+      for (const [semantic, name] of Object.entries(alternative.bindings)) {
+        if (semanticByEnvironment.has(name) && semanticByEnvironment.get(name) !== semantic) {
+          invalid(resourcePath, `Stack resource ${resource.id} assigns conflicting meanings to ${name}.`);
+        }
+        semanticByEnvironment.set(name, semantic);
+      }
+    }
+    return {
+      id: resource.id,
+      kind: resource.kind,
+      environmentAlternatives,
+      optionalBindings,
+    };
   });
   if (new Set(parsed.map(({ id }) => id)).size !== parsed.length) {
     invalid(resourcePath, '## Resources contains a duplicate resource id.');
@@ -226,6 +280,29 @@ export function parseStackResourceLines(lines, {
   return parsed;
 }
 
+function normalizeResourceBindings(value, resourcePath, resourceId, {
+  allowEmpty = false,
+} = {}) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    invalid(resourcePath, `Stack resource ${resourceId} has invalid semantic environment bindings.`);
+  }
+  const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+  if (!allowEmpty && entries.length === 0) {
+    invalid(resourcePath, `Stack resource ${resourceId} has an empty environment alternative.`);
+  }
+  if (
+    entries.some(([semantic, name]) => (
+      !RESOURCE_SEMANTIC_PATTERN.test(semantic)
+      || typeof name !== 'string'
+      || !ENVIRONMENT_NAME_PATTERN.test(name)
+    ))
+    || new Set(entries.map(([, name]) => name)).size !== entries.length
+  ) {
+    invalid(resourcePath, `Stack resource ${resourceId} has invalid semantic environment bindings.`);
+  }
+  return Object.fromEntries(entries);
+}
+
 function resources(all, piecePath) {
   return parseStackResourceLines(all.has('Resources') ? all.get('Resources') : undefined, {
     path: piecePath,

package/src/index/stack-preflight.js

@@ -1,8 +1,8 @@
-function present(environment, name, allowEmpty) {
+function present(environment, name, allowEmpty = false) {
   if (!Object.hasOwn(environment, name) || typeof environment[name] !== 'string') return false;
   const value = environment[name].trim();
   if (value === `$${name}` || value === `\${${name}}`) return false;
-  return value.length > 0 || allowEmpty.includes(name);
+  return value.length > 0 || allowEmpty;
 }
 
 /** Core reports declarations; each Stack component defines their meaning. */
@@ -11,11 +11,15 @@ export function missingStackResources({ environment = process.env, resources = [
     throw new TypeError('Stack resource inspection requires an environment object and resource declarations.');
   }
   return resources.flatMap(({ component, resource }) => {
-    const satisfied = resource.environmentAlternatives.some(({ required, allowEmpty }) => (
-      required.every((name) => present(environment, name, allowEmpty))
+    const satisfied = resource.environmentAlternatives.some(({ bindings, allowEmpty }) => (
+      Object.entries(bindings).every(([semantic, name]) => (
+        present(environment, name, allowEmpty.includes(semantic))
+      ))
     ));
     if (satisfied) return [];
-    const alternatives = resource.environmentAlternatives.map(({ required }) => required.join(' + '));
+    const alternatives = resource.environmentAlternatives.map(({ bindings }) => (
+      Object.values(bindings).join(' + ')
+    ));
     return [{
       code: 'STACK_RESOURCE_MISSING',
       message: `Stack component ${component} requires ${resource.id}: ${alternatives.join(' OR ')}.`,