genesis-compiler 1.0.0 → 1.2.0

package/src/index/stack-piece.js

@@ -0,0 +1,283 @@
+import { GenesisError } from './errors.js';
+import { parseStackCommandLines } from './stack-command.js';
+import { parseStackEnvironmentFileLines } from './stack-environment-files.js';
+import { parseStackLaunchLines } from './stack-launch.js';
+import { parseStackWorkspaceSetupLines } from './stack-workspace-setup.js';
+import { normalizeSource } from './utils.js';
+
+const STACK_PIECE_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const STACK_CUSTOMIZATION_TITLE = /^# Stack customization: ([a-z0-9]+(?:-[a-z0-9]+)*)\s*$/u;
+const STACK_CUSTOMIZATION_FIELDS = new Set(['Description', 'Guidance', 'Deslop']);
+
+export function normalizeStackPieceId(value, {
+  code = 'STACK_PIECE_INVALID',
+  field = 'piece',
+} = {}) {
+  const id = String(value ?? '').trim();
+  if (!STACK_PIECE_ID_PATTERN.test(id)) {
+    throw new GenesisError(
+      code,
+      `Stack ${field} must use lowercase letters, digits, and single hyphens.`,
+      { [field]: value },
+    );
+  }
+  return id;
+}
+
+function invalid(piecePath, message, details = {}) {
+  throw new GenesisError('STACK_PIECE_INVALID', message, { path: piecePath, ...details });
+}
+
+function sections(source) {
+  const lines = source.split('\n');
+  const result = new Map();
+  let current = null;
+  for (let index = 0; index < lines.length; index += 1) {
+    const heading = lines[index].match(/^##\s+(.+?)\s*$/u);
+    if (heading) {
+      current = heading[1];
+      if (!result.has(current)) result.set(current, []);
+    } else if (current) result.get(current).push(lines[index]);
+  }
+  return result;
+}
+
+function textSection(all, name) {
+  return (all.get(name) || []).join('\n').trim();
+}
+
+function customizationSections(source, piecePath) {
+  const result = { add: {}, override: {} };
+  const seenModes = new Set();
+  let mode = null;
+  let field = null;
+  let content = [];
+
+  function finishField() {
+    if (!field) return;
+    const value = content.join('\n').trim();
+    if (!value) invalid(piecePath, `Stack customization ${mode} ${field} must not be empty.`);
+    result[mode.toLowerCase()][field.toLowerCase()] = value;
+    field = null;
+    content = [];
+  }
+
+  for (const line of source.split('\n')) {
+    if (STACK_CUSTOMIZATION_TITLE.test(line)) continue;
+    const modeHeading = line.match(/^##\s+(.+?)\s*$/u);
+    if (modeHeading) {
+      finishField();
+      if (!['Add', 'Override'].includes(modeHeading[1]) || seenModes.has(modeHeading[1])) {
+        invalid(piecePath, `Unknown or duplicate customization section: ${modeHeading[1]}.`);
+      }
+      mode = modeHeading[1];
+      seenModes.add(mode);
+      continue;
+    }
+    const fieldHeading = line.match(/^###\s+(.+?)\s*$/u);
+    if (fieldHeading) {
+      finishField();
+      if (!mode || !STACK_CUSTOMIZATION_FIELDS.has(fieldHeading[1])) {
+        invalid(piecePath, `Unknown or misplaced customization field: ${fieldHeading[1]}.`);
+      }
+      const key = fieldHeading[1].toLowerCase();
+      if (Object.hasOwn(result[mode.toLowerCase()], key)) {
+        invalid(piecePath, `Duplicate ${mode} ${fieldHeading[1]} customization.`);
+      }
+      field = fieldHeading[1];
+      continue;
+    }
+    if (/^#{1,3}\s+/u.test(line)) invalid(piecePath, `Unknown customization heading: ${line.trim()}.`);
+    if (field) content.push(line);
+    else if (line.trim()) {
+      invalid(piecePath, 'Customization content must be below Description, Guidance, or Deslop.');
+    }
+  }
+  finishField();
+  if (Object.values(result).every((values) => Object.keys(values).length === 0)) {
+    invalid(piecePath, 'Stack customization must add or override Description, Guidance, or Deslop.');
+  }
+  return result;
+}
+
+function idList(all, name, piecePath, { required = false } = {}) {
+  const lines = (all.get(name) || []).filter((line) => line.trim());
+  if (lines.length === 0) {
+    if (required) invalid(piecePath, `Stack piece requires ## ${name}.`);
+    return [];
+  }
+  if (lines.length === 1 && /^- Nothing\.[ \t]*$/u.test(lines[0])) return [];
+  const ids = lines.map((line) => {
+    const match = line.match(/^- `([a-z0-9]+(?:-[a-z0-9]+)*)`[ \t]*$/u);
+    if (!match) invalid(piecePath, `## ${name} must list backticked component ids or \`- Nothing.\`.`);
+    return match[1];
+  });
+  if (new Set(ids).size !== ids.length) invalid(piecePath, `## ${name} contains a duplicate id.`);
+  return ids;
+}
+
+function skill(all, piecePath) {
+  const lines = (all.get('Skill') || []).filter((line) => line.trim());
+  if (lines.length === 0) return null;
+  const values = {};
+  for (const line of lines) {
+    const match = line.match(/^- (Package|Path): `([^`\r\n]+)`[ \t]*$/u);
+    if (!match) invalid(piecePath, '## Skill entries must be Package or Path.');
+    if (match[1] === 'Package') {
+      if (values.package || !/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/u.test(match[2])) {
+        invalid(piecePath, '## Skill accepts one npm package name.');
+      }
+      values.package = match[2];
+      continue;
+    }
+    if (
+      match[2].includes('\0')
+      || match[2].includes('\\')
+      || match[2].startsWith('/')
+      || match[2].split('/').some((part) => !part || ['.', '..'].includes(part))
+    ) {
+      invalid(piecePath, '## Skill accepts one relative directory Path.');
+    }
+    if (values.path) invalid(piecePath, '## Skill accepts one Path.');
+    values.path = match[2];
+  }
+  if (!values.path) invalid(piecePath, '## Skill requires one Path.');
+  return {
+    package: values.package || null,
+    path: values.path,
+  };
+}
+
+function resources(all, piecePath) {
+  const source = textSection(all, 'Resources');
+  if (!source) return [];
+  const blocks = [...source.matchAll(/```json genesis-resource\s*\n([\s\S]*?)\n```/gu)];
+  const outside = source.replace(/```json genesis-resource\s*\n[\s\S]*?\n```/gu, '').trim();
+  if (outside || blocks.length === 0) {
+    invalid(piecePath, '## Resources may contain only `json genesis-resource` fenced objects.');
+  }
+  const parsed = blocks.map((match) => {
+    let resource;
+    try { resource = JSON.parse(match[1]); } catch (error) {
+      invalid(piecePath, `A Stack resource is invalid JSON: ${error.message}`);
+    }
+    if (
+      !resource
+      || typeof resource.id !== 'string'
+      || !STACK_PIECE_ID_PATTERN.test(resource.id)
+      || !Array.isArray(resource.environmentAlternatives)
+      || resource.environmentAlternatives.length === 0
+    ) {
+      invalid(piecePath, 'A Stack resource needs an id and at least one environment alternative.');
+    }
+    const environmentAlternatives = resource.environmentAlternatives.map((alternative) => {
+      const required = alternative?.required;
+      const allowEmpty = alternative?.allowEmpty || [];
+      if (
+        !Array.isArray(required)
+        || !Array.isArray(allowEmpty)
+      ) {
+        invalid(piecePath, `Stack resource ${resource.id} has an invalid environment alternative.`);
+      }
+      const names = [...required, ...allowEmpty];
+      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
+        || new Set(allowEmpty).size !== allowEmpty.length
+      ) invalid(piecePath, `Stack resource ${resource.id} has an invalid environment alternative.`);
+      return { required: [...required], allowEmpty: [...allowEmpty] };
+    });
+    return { id: resource.id, environmentAlternatives };
+  });
+  if (new Set(parsed.map(({ id }) => id)).size !== parsed.length) {
+    invalid(piecePath, '## Resources contains a duplicate resource id.');
+  }
+  return parsed;
+}
+
+/**
+ * Stack pieces are guidance, not a second programming language. Genesis reads
+ * only the few sections it uses and deliberately ignores explanatory sections.
+ */
+export function parseStackPieceSource(value, {
+  expectedId,
+  path: piecePath = 'stack piece',
+} = {}) {
+  const source = normalizeSource(value);
+  const title = source.match(/^# Stack piece: ([a-z0-9]+(?:-[a-z0-9]+)*)\s*$/mu);
+  if (!title) invalid(piecePath, 'Stack piece needs `# Stack piece: piece-id`.');
+  const id = normalizeStackPieceId(title[1]);
+  if (expectedId && id !== expectedId) invalid(piecePath, `Stack piece id must be ${expectedId}.`);
+  const all = sections(source);
+  const description = textSection(all, 'Description');
+  const guidance = textSection(all, 'Guidance');
+  const deslop = textSection(all, 'Deslop');
+  if (!description) invalid(piecePath, 'Stack piece needs Description.');
+  const commands = parseStackCommandLines(all.get('Commands') || [], { path: piecePath });
+  const environmentFiles = parseStackEnvironmentFileLines(
+    all.has('Environment files') ? all.get('Environment files') : undefined,
+    { path: piecePath },
+  );
+  const launch = parseStackLaunchLines(all.has('Launch') ? all.get('Launch') : undefined, {
+    path: piecePath,
+  });
+  const workspaceSetup = parseStackWorkspaceSetupLines(
+    all.has('Workspace setup') ? all.get('Workspace setup') : undefined,
+    { path: piecePath },
+  );
+  return {
+    id,
+    description,
+    guidance,
+    requires: idList(all, 'Requires', piecePath, { required: true }),
+    conflicts: idList(all, 'Conflicts', piecePath),
+    indexers: idList(all, 'Indexers', piecePath),
+    skill: skill(all, piecePath),
+    resources: resources(all, piecePath),
+    commands: commands.map(({ line: _line, ...command }) => command),
+    environmentFiles: environmentFiles || [],
+    launchTargets: launch?.targets || [],
+    workspaceSetupSteps: workspaceSetup || [],
+    deslop,
+  };
+}
+
+export function parseStackPieceCustomizationSource(value, {
+  expectedId,
+  path: piecePath = 'stack customization',
+} = {}) {
+  const source = normalizeSource(value);
+  const titles = source.split('\n')
+    .map((line) => line.match(STACK_CUSTOMIZATION_TITLE))
+    .filter(Boolean);
+  if (titles.length !== 1) invalid(piecePath, 'Stack customization needs `# Stack customization: piece-id`.');
+  const id = normalizeStackPieceId(titles[0][1]);
+  if (expectedId && id !== expectedId) invalid(piecePath, `Stack customization id must be ${expectedId}.`);
+  return {
+    id,
+    ...customizationSections(source, piecePath),
+  };
+}
+
+function customizedText(original, override, addition) {
+  return [override ?? original, addition].filter(Boolean).join('\n\n');
+}
+
+export function applyStackPieceCustomization(piece, customization) {
+  return {
+    ...piece,
+    description: customizedText(
+      piece.description,
+      customization.override.description,
+      customization.add.description,
+    ),
+    guidance: customizedText(
+      piece.guidance,
+      customization.override.guidance,
+      customization.add.guidance,
+    ),
+    deslop: customizedText(piece.deslop, customization.override.deslop, customization.add.deslop),
+  };
+}

package/src/index/stack-preflight.js

@@ -0,0 +1,25 @@
+function present(environment, name, allowEmpty) {
+  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);
+}
+
+/** Core reports declarations; each Stack component defines their meaning. */
+export function missingStackResources({ environment = process.env, resources = [] } = {}) {
+  if (!environment || typeof environment !== 'object' || !Array.isArray(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))
+    ));
+    if (satisfied) return [];
+    const alternatives = resource.environmentAlternatives.map(({ required }) => required.join(' + '));
+    return [{
+      code: 'STACK_RESOURCE_MISSING',
+      message: `Stack component ${component} requires ${resource.id}: ${alternatives.join(' OR ')}.`,
+      details: { component, resource: resource.id, alternatives },
+    }];
+  });
+}

package/src/index/stack-process.js

@@ -0,0 +1,25 @@
+import path from 'node:path';
+
+export function parseBacktickedArguments(source) {
+  const matches = [...source.matchAll(/`([^`\r\n]+)`/gu)];
+  if (matches.length === 0 || matches.map((match) => match[0]).join(' ') !== source) return null;
+  return matches.map((match) => match[1]);
+}
+
+export function isSafeProcessExecutable(command, { allowPlaceholders = false } = {}) {
+  return typeof command === 'string'
+    && Boolean(command)
+    && !/[\s\0]/u.test(command)
+    && (allowPlaceholders || !/[{}]/u.test(command))
+    && !path.isAbsolute(command)
+    && !command.split(/[\\/]/u).includes('..');
+}
+
+export function isCanonicalProjectWorkdir(value) {
+  return typeof value === 'string'
+    && Boolean(value)
+    && !/[\0\r\n\\]/u.test(value)
+    && !path.posix.isAbsolute(value)
+    && path.posix.normalize(value) === value
+    && !value.split('/').some((part) => !part || part === '..');
+}

package/src/index/stack-workspace-setup.js

@@ -0,0 +1,129 @@
+import { GenesisError } from './errors.js';
+import {
+  isCanonicalProjectWorkdir,
+  isSafeProcessExecutable,
+  parseBacktickedArguments,
+} from './stack-process.js';
+
+const PREPARE_LINE = /^- Prepare `([^`\r\n]+)` with (.+?):[ \t]+(.+)$/u;
+const RUNTIME_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const READY_WHEN_SUFFIX = /^(.*?)[ \t]+when `([^`\r\n]+)` exists$/u;
+const WORKDIR_SUFFIX = /^(.*?)[ \t]+in `([^`\r\n]+)`$/u;
+
+function invalid(setupPath, message, line, details = {}) {
+  throw new GenesisError('STACK_WORKSPACE_SETUP_INVALID', message, {
+    path: setupPath,
+    ...(line === undefined ? {} : { line }),
+    ...details,
+  });
+}
+
+function parseRuntimeRequirements(source, setupPath, line) {
+  const runtimes = parseBacktickedArguments(source);
+  if (!runtimes) {
+    invalid(
+      setupPath,
+      'Workspace setup runtimes must be separate backticked technology ids.',
+      line,
+    );
+  }
+  const normalized = runtimes.map((runtime) => {
+    if (!RUNTIME_ID.test(runtime)) {
+      invalid(
+        setupPath,
+        'Workspace setup runtimes must use lowercase letters, digits, and single hyphens.',
+        line,
+        { runtime },
+      );
+    }
+    return runtime;
+  });
+  if (new Set(normalized).size !== normalized.length) {
+    invalid(setupPath, 'A Workspace setup step contains a duplicate runtime.', line);
+  }
+  return normalized;
+}
+
+export function parseStackWorkspaceSetupLines(lines, {
+  path: setupPath = 'stack workspace setup',
+} = {}) {
+  if (lines === undefined) return null;
+  const entries = lines.map((line) => line.trim()).filter(Boolean);
+  if (entries.length === 1 && entries[0] === '- Nothing.') return [];
+  const steps = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const source = lines[index].trim();
+    if (!source) continue;
+    const line = index + 1;
+    const entry = source.match(PREPARE_LINE);
+    if (!entry) {
+      invalid(
+        setupPath,
+        'Every Workspace setup entry must use `- Prepare `label` with `runtime` [in `workdir`] [when `path` exists]: `command` `argument`...`.',
+        line,
+        { observed: source },
+      );
+    }
+    const label = entry[1].trim();
+    if (!label || /[\0\r\n]/u.test(label)) {
+      invalid(setupPath, 'Workspace setup labels must be non-empty single lines.', line);
+    }
+    const readyEntry = entry[2].match(READY_WHEN_SUFFIX);
+    const setupSource = readyEntry ? readyEntry[1] : entry[2];
+    const readyWhen = readyEntry ? readyEntry[2] : '';
+    if (readyWhen && (readyWhen === '.' || !isCanonicalProjectWorkdir(readyWhen))) {
+      invalid(
+        setupPath,
+        'Workspace setup readiness paths must be canonical project-relative paths.',
+        line,
+      );
+    }
+    const workdirEntry = setupSource.match(WORKDIR_SUFFIX);
+    const runtimeSource = workdirEntry ? workdirEntry[1] : setupSource;
+    const workdir = workdirEntry ? workdirEntry[2] : '.';
+    if (!isCanonicalProjectWorkdir(workdir)) {
+      invalid(setupPath, 'Workspace setup workdir must be a canonical project-relative directory.', line);
+    }
+    const argv = parseBacktickedArguments(entry[3]);
+    if (!argv || argv.some((value) => value.includes('\0')) || !isSafeProcessExecutable(argv[0])) {
+      invalid(
+        setupPath,
+        'Workspace setup command and arguments must be separate non-empty backticked values with a safe executable.',
+        line,
+      );
+    }
+    steps.push({
+      label,
+      argv,
+      runtimeRequirements: parseRuntimeRequirements(runtimeSource, setupPath, line),
+      workdir,
+      ...(readyWhen ? { readyWhen } : {}),
+    });
+  }
+  if (steps.length === 0) {
+    invalid(setupPath, '## Workspace setup needs at least one Prepare entry.');
+  }
+  return steps;
+}
+
+export function composeStackWorkspaceSetup(components, projectSteps) {
+  if (projectSteps !== null) return { source: 'project', steps: projectSteps, diagnostics: [] };
+  const declarations = components
+    .filter((component) => component.workspaceSetupSteps.length > 0)
+    .map((component) => ({
+      source: `component:${component.id}`,
+      steps: component.workspaceSetupSteps,
+    }));
+  if (declarations.length === 0) return { source: null, steps: [], diagnostics: [] };
+  if (declarations.length === 1) return { ...declarations[0], diagnostics: [] };
+  const sources = declarations.map(({ source }) => source).sort();
+  return {
+    source: null,
+    steps: [],
+    diagnostics: [{
+      code: 'STACK_WORKSPACE_SETUP_AMBIGUOUS',
+      message: `Selected Stack components provide competing Workspace setup recipes: ${sources.join(', ')}. Add one project ## Workspace setup section to choose the exact recipe.`,
+      details: { sources },
+    }],
+  };
+}