genesis-compiler 1.0.0 → 1.1.0

package/src/index/assets.js

@@ -0,0 +1,18 @@
+import { readFile } from 'node:fs/promises';
+
+const root = new URL('../../', import.meta.url);
+const assets = {
+  work: new URL('prompts/work.txt', root),
+  describe: new URL('prompts/describe.txt', root),
+  reconcile: new URL('prompts/reconcile.txt', root),
+  deslop: new URL('prompts/deslop.txt', root),
+  program: new URL('prompts/program.txt', root),
+  blueprint: new URL('prompts/blueprint.txt', root),
+  review: new URL('prompts/review.txt', root),
+};
+
+export async function readInstalledAsset(name) {
+  const location = assets[name];
+  if (!location) throw new TypeError(`Unknown Genesis asset: ${name}.`);
+  return readFile(location, 'utf8');
+}

package/src/index/blueprint.js

@@ -0,0 +1,38 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { GenesisError } from './errors.js';
+import { BLUEPRINT_PATH } from './paths.js';
+import { normalizeSource } from './utils.js';
+
+export const BLUEPRINT_SKELETON_SOURCE = '# Blueprint\n\n';
+
+export function parseBlueprintSource(value, { requireDescription = false } = {}) {
+  const source = normalizeSource(value);
+  if (!/^# Blueprint[ \t]*$/mu.test(source)) {
+    throw new GenesisError('BLUEPRINT_INVALID', 'Blueprint needs one `# Blueprint` title.', {
+      path: BLUEPRINT_PATH,
+    });
+  }
+  const description = source.replace(/^# Blueprint[ \t]*\n?/mu, '').trim();
+  if (requireDescription && !description) {
+    throw new GenesisError('BLUEPRINT_INVALID', 'Blueprint needs a product description.', {
+      path: BLUEPRINT_PATH,
+    });
+  }
+  return { path: BLUEPRINT_PATH, source, description };
+}
+
+export async function readBlueprint(projectRoot, { required = false, requireDescription = false } = {}) {
+  try {
+    return parseBlueprintSource(await readFile(path.join(projectRoot, BLUEPRINT_PATH), 'utf8'), {
+      requireDescription,
+    });
+  } catch (error) {
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code) && !required) return null;
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code)) {
+      throw new GenesisError('BLUEPRINT_REQUIRED', `Blueprint does not exist: ${BLUEPRINT_PATH}.`);
+    }
+    throw error;
+  }
+}

package/src/index/check.js

@@ -0,0 +1,102 @@
+import { readBlueprint } from './blueprint.js';
+import { inspectProjectSkills } from './agent-skills.js';
+import { readStack } from './stack.js';
+import { asDiagnostic } from './errors.js';
+import { gitContext } from './git.js';
+import { inspectProgram } from './program.js';
+import { inspectVerification } from './project-state.js';
+import { missingStackResources } from './stack-preflight.js';
+
+function invalidResult(area, error) {
+  return {
+    status: 'invalid',
+    blueprint: area === 'blueprint' ? 'invalid' : 'valid',
+    stack: area === 'stack' ? 'invalid' : 'unknown',
+    skills: area === 'skills' ? 'invalid' : 'unknown',
+    program: 'unknown',
+    resources: 'unknown',
+    verification: 'unknown',
+    programFiles: [],
+    subsystems: [],
+    diagnostics: [asDiagnostic(error)],
+    guidance: error.message,
+  };
+}
+
+export async function checkProject({ environment = process.env, projectRoot } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  try {
+    await readBlueprint(root, { required: true, requireDescription: true });
+  } catch (error) {
+    return invalidResult('blueprint', error);
+  }
+
+  let stack;
+  try {
+    stack = await readStack(root);
+  } catch (error) {
+    return invalidResult('stack', error);
+  }
+
+  let program;
+  try {
+    program = await inspectProgram(root);
+  } catch (error) {
+    program = {
+      status: 'invalid',
+      files: [],
+      subsystems: [],
+      diagnostic: asDiagnostic(error),
+    };
+  }
+  let skills;
+  try {
+    skills = await inspectProjectSkills({ projectRoot: root, stack });
+  } catch (error) {
+    skills = { status: 'invalid', diagnostics: [asDiagnostic(error)], skills: [] };
+  }
+  const missingResources = missingStackResources({ environment, resources: stack.resources });
+  const verification = await inspectVerification({ projectRoot: root, stack });
+  const diagnostics = [
+    ...(program.diagnostic ? [program.diagnostic] : []),
+    ...skills.diagnostics,
+    ...missingResources,
+    ...(verification.status === 'invalid' ? [{
+      code: 'VERIFICATION_EVIDENCE_INVALID',
+      message: 'Saved verification evidence is malformed.',
+    }] : []),
+  ];
+
+  const guidance = [];
+  if (program.status === 'missing') guidance.push('Generate an explanatory Program prompt with genesis prompt --task program.');
+  if (program.status === 'invalid') guidance.push('Repair the Program with genesis prompt --task program.');
+  if (skills.status === 'missing') guidance.push('Run genesis init to install selected project Agent Skills.');
+  if (skills.status === 'invalid') guidance.push('Repair the reported Agent Skill or managed-skill manifest.');
+  if (missingResources.length > 0) {
+    guidance.push(`${missingResources.map(({ message }) => message).join(' ')} Prompt generation remains available.`);
+  }
+  if (['missing', 'stale'].includes(verification.status)) guidance.push('Run genesis verify to refresh concrete evidence.');
+  if (verification.status === 'unconfigured') guidance.push('Add project verification commands to genesis/stack.md.');
+  guidance.push('Use genesis prompt --task review for a semantic, evidence-based comparison.');
+
+  const needsAttention = program.status === 'missing'
+    || skills.status === 'missing'
+    || missingResources.length > 0
+    || ['missing', 'stale', 'unconfigured'].includes(verification.status);
+
+  return {
+    status: program.status === 'invalid' || skills.status === 'invalid' || verification.status === 'invalid'
+      ? 'invalid'
+      : needsAttention ? 'attention' : 'ok',
+    blueprint: 'valid',
+    stack: 'valid',
+    skills: skills.status,
+    program: program.status,
+    resources: missingResources.length > 0 ? 'missing' : 'inputs-present',
+    verification: verification.status,
+    programFiles: program.files,
+    subsystems: program.subsystems,
+    diagnostics,
+    guidance: guidance.join(' '),
+  };
+}

package/src/index/code-index.js

@@ -0,0 +1,283 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { astGrepCodeIndexers } from './code-indexers/ast-grep.js';
+import { asDiagnostic } from './errors.js';
+import { gitContext } from './git.js';
+import { isProjectContentPath } from './paths.js';
+import { inspectProgram } from './program.js';
+import { gitVisibleFileStates } from './project-files.js';
+import { readStack } from './stack.js';
+import { sha256, stableJson, writeFileAtomic } from './utils.js';
+
+export const MACHINE_CITY_PATH = '.genesis/machine-city.json';
+export const PROGRAM_CITY_PATH = '.genesis/program-city.json';
+
+const INDEXERS = astGrepCodeIndexers;
+
+function directoryId(value) {
+  return `directory:${value || '.'}`;
+}
+
+function fileId(value) {
+  return `file:${value}`;
+}
+
+function subsystemId(value) {
+  return `subsystem:${value}`;
+}
+
+function operationId(module) {
+  return `operation:${module.subsystem}/${module.name}`;
+}
+
+function parentDirectory(value) {
+  const parent = path.posix.dirname(value);
+  return parent === '.' ? '' : parent;
+}
+
+function directoryRecords(paths) {
+  const directories = new Set(['']);
+  for (const value of paths) {
+    let current = parentDirectory(value);
+    while (true) {
+      directories.add(current);
+      if (!current) break;
+      current = parentDirectory(current);
+    }
+  }
+  return [...directories].sort().map((directory) => ({
+    id: directoryId(directory),
+    path: directory,
+    title: directory ? path.posix.basename(directory) : 'Project',
+    parentId: directory ? directoryId(parentDirectory(directory)) : null,
+  }));
+}
+
+function subsystemRecords(subsystems) {
+  const paths = new Set();
+  for (const subsystem of subsystems) {
+    const segments = subsystem.split('/');
+    for (let count = 1; count <= segments.length; count += 1) {
+      paths.add(segments.slice(0, count).join('/'));
+    }
+  }
+  return [...paths].sort().map((subsystem) => ({
+    id: subsystemId(subsystem),
+    path: subsystem,
+    title: path.posix.basename(subsystem).replace(/-/gu, ' '),
+    parentId: subsystem.includes('/') ? subsystemId(parentDirectory(subsystem)) : null,
+  }));
+}
+
+function normalizedFunction(entry, file, extractor) {
+  const qualifiedName = entry.qualifiedName || entry.name;
+  return {
+    id: `function:${file.path}:${qualifiedName}:${entry.kind}:${entry.line}:${entry.column}`,
+    name: entry.name,
+    qualifiedName,
+    kind: entry.kind,
+    visibility: entry.visibility,
+    container: entry.container || null,
+    path: file.path,
+    fileId: fileId(file.path),
+    line: entry.line,
+    column: entry.column,
+    parameters: entry.parameters || [],
+    async: entry.async === true,
+    generator: entry.generator === true,
+    static: entry.static === true,
+    role: file.role,
+    language: file.language,
+    extractor,
+  };
+}
+
+function mergeIndexedFiles(contributions) {
+  const files = new Map();
+  const functions = [];
+  for (const contribution of contributions) {
+    for (const file of contribution.files || []) {
+      const existing = files.get(file.path);
+      const record = existing || {
+        id: fileId(file.path),
+        path: file.path,
+        language: file.language,
+        role: file.role,
+        mode: file.mode,
+        bytes: file.bytes,
+        lines: file.lines,
+        hash: file.hash,
+        extractors: [],
+        functionIds: [],
+      };
+      if (!record.extractors.includes(contribution.extractor)) record.extractors.push(contribution.extractor);
+      for (const entry of file.functions || []) {
+        const normalized = normalizedFunction(entry, file, contribution.extractor);
+        functions.push(normalized);
+        record.functionIds.push(normalized.id);
+      }
+      files.set(file.path, record);
+    }
+  }
+  return {
+    files: [...files.values()].sort((left, right) => left.path.localeCompare(right.path)),
+    functions: functions.sort((left, right) => (
+      left.path.localeCompare(right.path) || left.line - right.line || left.qualifiedName.localeCompare(right.qualifiedName)
+    )),
+  };
+}
+
+function machineCity({ components, contributions, diagnostics, indexers }) {
+  const merged = mergeIndexedFiles(contributions);
+  const visibility = new Map(merged.functions.map((entry) => [entry.id, entry.visibility]));
+  const codeHash = sha256(stableJson(merged.files.map(({ path: filePath, hash, mode }) => ({
+    path: filePath,
+    hash,
+    mode,
+  }))));
+  return {
+    schema: 'genesis.machine-city.v1',
+    schemaVersion: 1,
+    status: indexers.length === 0 ? 'unconfigured' : diagnostics.length > 0 ? 'completed-with-warning' : 'current',
+    codeHash,
+    stackComponents: components,
+    indexers,
+    diagnostics,
+    functions: merged.functions,
+    districts: directoryRecords(merged.files.map(({ path: filePath }) => filePath)),
+    buildings: merged.files.map((file) => ({
+      ...file,
+      districtId: directoryId(parentDirectory(file.path)),
+      title: path.posix.basename(file.path),
+      publicFunctionCount: file.functionIds.filter((id) => visibility.get(id) === 'public').length,
+      internalFunctionCount: file.functionIds.filter((id) => visibility.get(id) === 'internal').length,
+    })),
+  };
+}
+
+async function programCity(projectRoot) {
+  try {
+    const program = await inspectProgram(projectRoot);
+    const operations = program.modules.map((module) => ({
+      id: operationId(module),
+      name: module.name,
+      title: module.title,
+      description: module.description,
+      publicContract: module.publicContract,
+      implementationMap: module.implementationMap,
+      path: module.path,
+      subsystem: module.subsystem,
+      districtId: subsystemId(module.subsystem),
+      sources: module.sources,
+      sourceFileIds: module.sources.map(fileId),
+    }));
+    return {
+      schema: 'genesis.program-city.v1',
+      schemaVersion: 1,
+      status: program.status,
+      programHash: sha256(stableJson(operations)),
+      diagnostics: [],
+      districts: subsystemRecords(program.subsystems),
+      buildings: operations,
+      links: operations.flatMap((operation) => operation.sourceFileIds.map((targetId) => ({
+        kind: 'implemented-by',
+        fromId: operation.id,
+        toId: targetId,
+      }))),
+    };
+  } catch (error) {
+    return {
+      schema: 'genesis.program-city.v1',
+      schemaVersion: 1,
+      status: 'invalid',
+      programHash: sha256('invalid'),
+      diagnostics: [asDiagnostic(error)],
+      districts: [],
+      buildings: [],
+      links: [],
+    };
+  }
+}
+
+async function writeIfChanged(projectRoot, relativePath, value) {
+  const location = path.join(projectRoot, relativePath);
+  const source = stableJson(value);
+  try {
+    if (await readFile(location, 'utf8') === source) return false;
+  } catch (error) {
+    if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) throw error;
+  }
+  await writeFileAtomic(location, source);
+  return true;
+}
+
+function functionMatches(entry, queries) {
+  if (queries.length === 0) return false;
+  const haystack = [entry.name, entry.qualifiedName, entry.path, entry.kind, entry.visibility]
+    .join('\n')
+    .toLowerCase();
+  return queries.every((query) => haystack.includes(query.toLowerCase()));
+}
+
+function formatCount(value, singular) {
+  return `${value} ${singular}${value === 1 ? '' : 's'}`;
+}
+
+export async function buildProjectIndex({ projectRoot, queries = [], write = true } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const stack = await readStack(root);
+  const states = await gitVisibleFileStates(root, { includePath: isProjectContentPath });
+  const files = [...states]
+    .filter(([, state]) => state.exists && !state.symlink && !state.special && state.hash)
+    .map(([filePath, state]) => ({ path: filePath, hash: state.hash, mode: state.mode }));
+  const indexers = [...new Set(stack.components.flatMap((component) => component.indexers || []))].sort();
+  const contributions = [];
+  const diagnostics = [];
+  for (const id of indexers) {
+    const indexer = INDEXERS.get(id);
+    if (!indexer) {
+      diagnostics.push({ code: 'CODE_INDEXER_UNAVAILABLE', message: `No installed code indexer exists for ${id}.` });
+      continue;
+    }
+    try {
+      const contribution = await indexer.extract({ files, projectRoot: root });
+      contributions.push({ ...contribution, extractor: id });
+      diagnostics.push(...(contribution.diagnostics || []).map((diagnostic) => ({ ...diagnostic, extractor: id })));
+    } catch (error) {
+      diagnostics.push({ ...asDiagnostic(error), code: 'CODE_INDEXER_FAILED', extractor: id });
+    }
+  }
+  const machine = machineCity({
+    components: stack.components.map(({ id }) => id),
+    contributions,
+    diagnostics,
+    indexers,
+  });
+  const program = await programCity(root);
+  const changedFiles = [];
+  if (write) {
+    if (await writeIfChanged(root, MACHINE_CITY_PATH, machine)) changedFiles.push(MACHINE_CITY_PATH);
+    if (await writeIfChanged(root, PROGRAM_CITY_PATH, program)) changedFiles.push(PROGRAM_CITY_PATH);
+  }
+  const allMatches = machine.functions.filter((entry) => functionMatches(entry, queries));
+  const allDiagnostics = [...diagnostics, ...program.diagnostics];
+  return {
+    status: allDiagnostics.length > 0 ? 'completed-with-warning' : 'ready',
+    summary: [
+      `Indexed ${formatCount(machine.functions.length, 'function')}`,
+      `in ${formatCount(machine.buildings.length, 'file')}`,
+      `and ${formatCount(program.buildings.length, 'Program operation')}.`,
+    ].join(' '),
+    paths: { machine: MACHINE_CITY_PATH, program: PROGRAM_CITY_PATH },
+    changedFiles,
+    diagnostics: allDiagnostics,
+    functionCount: machine.functions.length,
+    fileCount: machine.buildings.length,
+    operationCount: program.buildings.length,
+    totalMatches: allMatches.length,
+    matches: allMatches.slice(0, 200),
+    machine,
+    program,
+  };
+}