@puls-atlas/cli
Version:
The Puls Atlas CLI tool for managing Atlas projects
912 lines • 49 kB
JavaScript
import fs from 'fs';
import path from 'path';
import { createHash } from 'node:crypto';
import { normalizeOptionalString } from '../../utils/value.js';
import { readJsonFile } from '../../utils/file.js';
import { createSnapshotSelectedGuideSummary, createSnapshotSelectedSymbolSummary, createSnapshotSymbolKey, hasSemanticSnapshotSelectedSymbol, hasSnapshotArrayValues, isGenericSnapshotSymbolSummary } from './snapshotRuntime.js';
const ATLAS_SCOPE_NAME = '@limebooth';
const ATLAS_PACKAGE_PREFIX = 'atlas-';
const DEFAULT_SHARED_PACKAGE_NAME = '@limebooth/atlas-ai';
const DEFAULT_COPILOT_INSTRUCTIONS_PATH = '.github/copilot-instructions.md';
const DEFAULT_CONTEXT_LOCK_PATH = '.atlas/ai/context-lock.json';
const DEFAULT_CONTEXT_SNAPSHOT_PATH = '.atlas/ai/context-snapshot.json';
const DEFAULT_SHARED_AGENT_PATH = '.github/agents/atlas.agent.md';
const DEFAULT_SHARED_COPILOT_TEMPLATE_PATH = '.github/copilot-instructions.md';
const DEFAULT_PACKAGE_CONTEXT_RELATIVE_PATH = ['dist', 'ai-context.json'];
const DEFAULT_PACKAGE_GUIDES_RELATIVE_PATH = ['dist', 'ai-guides.json'];
const DEFAULT_PACKAGE_SYMBOLS_RELATIVE_PATH = ['dist', 'ai-symbols.json'];
const DEFAULT_START_AI_REFRESH_MODE = 'auto';
const DEFAULT_VERIFY_POLICY_MODE = 'localDevelopment';
const DEFAULT_WORKSPACE_ROOT_NAMES = ['app', 'functions', 'services', 'api'];
const SNAPSHOT_GUIDE_LIMIT_PER_PACKAGE = 4;
const SNAPSHOT_SYMBOL_LIMIT_PER_ENTRYPOINT = 3;
const SNAPSHOT_SYMBOL_LIMIT_PER_PACKAGE = 12;
const ATLAS_AI_CONSUMER_QUALITY_CONTRACT = Object.freeze({
maxBootstrapBytes: 225000,
maxSnapshotBytes: 100000,
maxGenericSelectedSymbols: 0,
minSnapshotCompressionFactor: 2
});
const ATLAS_AI_MATURITY_ORDER = ['inventory-only', 'symbol-enriched', 'guide-enriched'];
const ATLAS_AI_REQUIRED_ARTIFACTS = new Set(['context', 'symbols', 'guides']);
const ATLAS_AI_VERIFY_POLICY_MODES = new Set(['localDevelopment', 'ci', 'release']);
const ATLAS_AI_VERIFY_SEVERITIES = new Set(['ignore', 'warning', 'error']);
const START_AI_REFRESH_MODES = new Set(['auto', 'force', 'off']);
const normalizePathSeparators = value => value.split(path.sep).join('/');
const createChecksum = value => createHash('sha256').update(value).digest('hex');
const parseJsonText = (filePath, fileContent) => {
try {
return JSON.parse(fileContent);
} catch (error) {
throw new Error(`Invalid JSON in file: ${filePath}\nError: ${error.message}`);
}
};
const createJsonText = (data, options = {}) => {
const {
indent = 4,
trailingNewline = true
} = options;
const serializedJson = JSON.stringify(data, null, indent);
return trailingNewline ? `${serializedJson}\n` : serializedJson;
};
const getUtf8ByteLength = value => Buffer.byteLength(String(value ?? ''), 'utf8');
const readTextFile = (filePath, dependencies = {}) => {
const {
fsImpl = fs
} = dependencies;
if (!fsImpl.existsSync(filePath)) {
return null;
}
try {
return fsImpl.readFileSync(filePath, 'utf-8');
} catch (error) {
throw new Error(`Failed to read file: ${filePath}\nError: ${error.message}`);
}
};
const resolvePackageRootPath = (cwd, packageName, pathImpl = path) => {
const segments = packageName.split('/');
return pathImpl.join(cwd, 'node_modules', ...segments);
};
const normalizeWorkspaceRootsOption = value => {
if (Array.isArray(value)) {
return value.map(entry => normalizeOptionalString(entry)).filter(Boolean);
}
const normalizedValue = normalizeOptionalString(value);
if (!normalizedValue) {
return [];
}
return normalizedValue.split(',').map(entry => normalizeOptionalString(entry)).filter(Boolean);
};
const createUniquePathList = values => {
const uniqueValues = [];
const seen = new Set();
for (const value of values) {
const normalizedValue = normalizeOptionalString(value);
if (!normalizedValue || seen.has(normalizedValue)) {
continue;
}
seen.add(normalizedValue);
uniqueValues.push(normalizedValue);
}
return uniqueValues;
};
const replaceTemplateVariables = (templateText, replacements) => {
let renderedText = templateText;
for (const [placeholderName, replacementValue] of Object.entries(replacements)) {
renderedText = renderedText.replaceAll(`{{${placeholderName}}}`, String(replacementValue ?? ''));
}
return renderedText;
};
const isAtlasAgentFilePath = value => {
const normalizedValue = normalizeOptionalString(value);
return Boolean(normalizedValue && normalizedValue.startsWith('.github/agents/') && normalizedValue.endsWith('.agent.md'));
};
const isAtlasSkillFilePath = value => {
const normalizedValue = normalizeOptionalString(value);
return Boolean(normalizedValue && normalizedValue.startsWith('.github/skills/') && normalizedValue.endsWith('/SKILL.md'));
};
const getSharedAgentRelativePaths = (sharedManifest = {}) => {
const recommendedAgentPath = normalizeOptionalString(sharedManifest?.recommendedAgent?.path) ?? DEFAULT_SHARED_AGENT_PATH;
const generatedAgentPaths = Array.isArray(sharedManifest?.consumerGeneratedFiles) ? sharedManifest.consumerGeneratedFiles.filter(isAtlasAgentFilePath) : [];
return createUniquePathList([recommendedAgentPath, ...generatedAgentPaths]);
};
const getSharedSkillRelativePaths = (sharedManifest = {}) => createUniquePathList(Array.isArray(sharedManifest?.consumerGeneratedFiles) ? sharedManifest.consumerGeneratedFiles.filter(isAtlasSkillFilePath) : []);
const normalizeSupportedPackagePolicy = value => {
if (typeof value === 'string') {
const name = normalizeOptionalString(value);
return name ? {
name,
minimumMaturity: null,
requiredArtifacts: ['context', 'symbols']
} : null;
}
const name = normalizeOptionalString(value?.name);
if (!name) {
return null;
}
const minimumMaturity = normalizeOptionalString(value?.minimumMaturity);
const requiredArtifacts = Array.isArray(value?.requiredArtifacts) ? value.requiredArtifacts.map(entry => normalizeOptionalString(entry)).filter(entry => entry && ATLAS_AI_REQUIRED_ARTIFACTS.has(entry)) : ['context', 'symbols'];
return {
name,
minimumMaturity: minimumMaturity && ATLAS_AI_MATURITY_ORDER.includes(minimumMaturity) ? minimumMaturity : null,
requiredArtifacts: requiredArtifacts.length > 0 ? requiredArtifacts : ['context', 'symbols']
};
};
const createSupportedPackagePolicies = values => {
const policiesByName = new Map();
for (const value of Array.isArray(values) ? values : []) {
const policy = normalizeSupportedPackagePolicy(value);
if (!policy) {
continue;
}
policiesByName.set(policy.name, policy);
}
return [...policiesByName.values()].sort((left, right) => left.name.localeCompare(right.name));
};
const createSupportedPackagePolicyLookup = values => new Map(createSupportedPackagePolicies(values).map(policy => [policy.name, policy]));
const normalizeVerificationPolicyMode = value => {
const normalizedValue = normalizeOptionalString(value);
if (normalizedValue && ATLAS_AI_VERIFY_POLICY_MODES.has(normalizedValue)) {
return normalizedValue;
}
return DEFAULT_VERIFY_POLICY_MODE;
};
const resolveVerificationPolicyMode = options => {
if (normalizeOptionalString(options?.policyMode)) {
return normalizeVerificationPolicyMode(options.policyMode);
}
if (options?.strict) {
return 'release';
}
return DEFAULT_VERIFY_POLICY_MODE;
};
const normalizeVerificationSeverity = value => {
const normalizedValue = normalizeOptionalString(value);
if (normalizedValue && ATLAS_AI_VERIFY_SEVERITIES.has(normalizedValue)) {
return normalizedValue;
}
return 'error';
};
const getVerificationSeverity = (sharedManifest, policyMode, findingType, fallbackSeverity) => normalizeVerificationSeverity(sharedManifest?.verificationPolicy?.[policyMode]?.[findingType] ?? fallbackSeverity);
export const createVerificationFindingRecord = (severity, message, options = {}) => {
const title = normalizeOptionalString(options.title) ?? normalizeOptionalString(message) ?? '';
const items = (Array.isArray(options.items) ? options.items : []).map(entry => normalizeOptionalString(entry)).filter(Boolean);
return {
code: normalizeOptionalString(options.code),
items,
message: normalizeOptionalString(message) ?? title,
severity,
title
};
};
const pushVerificationFinding = (findings, severity, message, options = {}) => {
if (severity === 'ignore') {
return;
}
const record = createVerificationFindingRecord(severity, message, options);
findings.records.push(record);
if (severity === 'warning') {
findings.warnings.push(record.message);
return;
}
findings.issues.push(record.message);
};
export const logVerificationFindingRecords = (loggerImpl, findingRecords = []) => {
for (const finding of Array.isArray(findingRecords) ? findingRecords : []) {
if (finding.items.length > 0) {
loggerImpl.section(finding.title, finding.items, {
severity: 'warning'
});
continue;
}
loggerImpl.warning(finding.message);
}
};
const isWorkspaceRootPath = (workspaceRootPath, dependencies = {}) => {
const {
fsImpl = fs,
pathImpl = path
} = dependencies;
if (normalizeOptionalString(workspaceRootPath) === normalizeOptionalString(pathImpl.resolve(workspaceRootPath))) {
if (fsImpl.existsSync(pathImpl.join(workspaceRootPath, 'package.json')) || fsImpl.existsSync(pathImpl.join(workspaceRootPath, 'node_modules'))) {
return true;
}
}
return fsImpl.existsSync(pathImpl.join(workspaceRootPath, 'package.json')) || fsImpl.existsSync(pathImpl.join(workspaceRootPath, 'node_modules'));
};
const resolveWorkspaceRootPaths = (cwd, options = {}, dependencies = {}) => {
const {
pathImpl = path
} = dependencies;
const configuredRootNames = normalizeWorkspaceRootsOption(options.workspaceRoots);
const candidateRootPaths = [...configuredRootNames.map(rootName => pathImpl.resolve(cwd, rootName)), ...DEFAULT_WORKSPACE_ROOT_NAMES.map(rootName => pathImpl.resolve(cwd, rootName)), cwd];
return createUniquePathList(candidateRootPaths).filter(workspaceRootPath => {
if (workspaceRootPath === cwd) {
return true;
}
return isWorkspaceRootPath(workspaceRootPath, dependencies);
});
};
const resolveWorkspacePackageManifestPaths = (cwd, workspaceRootPaths, dependencies = {}) => {
const {
fsImpl = fs,
pathImpl = path
} = dependencies;
return workspaceRootPaths.map(workspaceRootPath => pathImpl.join(workspaceRootPath, 'package.json')).filter(packageJsonPath => fsImpl.existsSync(packageJsonPath)).map(packageJsonPath => normalizePathSeparators(pathImpl.relative(cwd, packageJsonPath)));
};
const resolveSharedPackageLocation = (cwd, sharedPackageName, workspaceRootPaths, dependencies = {}) => {
const {
pathImpl = path
} = dependencies;
const candidateRootPaths = createUniquePathList([cwd, ...workspaceRootPaths]);
const attemptedManifestPaths = [];
for (const workspaceRootPath of candidateRootPaths) {
const sharedPackageRootPath = resolvePackageRootPath(workspaceRootPath, sharedPackageName, pathImpl);
const sharedManifestPath = pathImpl.join(sharedPackageRootPath, 'atlas-ai-manifest.json');
const sharedManifestText = readTextFile(sharedManifestPath, dependencies);
attemptedManifestPaths.push(sharedManifestPath);
if (sharedManifestText !== null) {
return {
sharedManifestPath,
sharedManifestText,
sharedPackageRootPath,
workspaceRootPath
};
}
}
throw new Error(`Atlas AI shared package was not found at any discovery root. Looked in: ${attemptedManifestPaths.join(', ')}. ` + 'Install the shared Atlas AI package before running this command.');
};
export const resolveOutputPaths = (cwd, options = {}, sharedManifest = {}, pathImpl = path) => {
const consumerManifestConventions = sharedManifest?.consumerManifestConventions ?? {};
const sharedAgentRelativePaths = getSharedAgentRelativePaths(sharedManifest);
const relativeSkillPaths = getSharedSkillRelativePaths(sharedManifest);
const leadAgentRelativePath = normalizeOptionalString(options.agentFile) ?? normalizeOptionalString(consumerManifestConventions.agentFile) ?? sharedAgentRelativePaths[0] ?? DEFAULT_SHARED_AGENT_PATH;
const relativeAgentPaths = createUniquePathList([leadAgentRelativePath, ...sharedAgentRelativePaths.filter(agentPath => agentPath !== sharedAgentRelativePaths[0])]);
const agentPaths = relativeAgentPaths.map(agentPath => pathImpl.resolve(cwd, agentPath));
const skillPaths = relativeSkillPaths.map(skillPath => pathImpl.resolve(cwd, skillPath));
const instructionsPath = pathImpl.resolve(cwd, normalizeOptionalString(options.output) ?? normalizeOptionalString(consumerManifestConventions.instructionsFile) ?? DEFAULT_COPILOT_INSTRUCTIONS_PATH);
const lockFilePath = pathImpl.resolve(cwd, normalizeOptionalString(options.lockFile) ?? normalizeOptionalString(consumerManifestConventions.lockFile) ?? DEFAULT_CONTEXT_LOCK_PATH);
const snapshotPath = pathImpl.resolve(cwd, normalizeOptionalString(options.snapshotFile) ?? normalizeOptionalString(consumerManifestConventions.snapshotFile) ?? DEFAULT_CONTEXT_SNAPSHOT_PATH);
return {
agentPath: agentPaths[0],
agentPaths,
instructionsPath,
lockFilePath,
skillPaths,
snapshotPath,
relativeAgentPath: relativeAgentPaths[0],
relativeAgentPaths,
relativeInstructionsPath: normalizePathSeparators(pathImpl.relative(cwd, instructionsPath)),
relativeLockFilePath: normalizePathSeparators(pathImpl.relative(cwd, lockFilePath)),
relativeSkillPaths,
relativeSnapshotPath: normalizePathSeparators(pathImpl.relative(cwd, snapshotPath)),
workspaceRootPath: cwd
};
};
const normalizeDirectoryEntryName = entry => {
if (typeof entry === 'string') {
return entry;
}
return entry?.name ?? '';
};
const listInstalledAtlasPackageEntries = (workspaceRootPaths, dependencies = {}) => {
const {
fsImpl = fs,
pathImpl = path
} = dependencies;
const entriesByName = new Map();
for (const workspaceRootPath of workspaceRootPaths) {
const scopeDirectory = pathImpl.join(workspaceRootPath, 'node_modules', ATLAS_SCOPE_NAME);
if (!fsImpl.existsSync(scopeDirectory)) {
continue;
}
const packageNames = fsImpl.readdirSync(scopeDirectory).map(normalizeDirectoryEntryName).filter(packageName => packageName.startsWith(ATLAS_PACKAGE_PREFIX)).sort((left, right) => left.localeCompare(right));
for (const packageName of packageNames) {
const fullPackageName = `${ATLAS_SCOPE_NAME}/${packageName}`;
if (entriesByName.has(fullPackageName)) {
continue;
}
entriesByName.set(fullPackageName, {
packageName: fullPackageName,
workspaceRootPath
});
}
}
return [...entriesByName.values()].sort((left, right) => left.packageName.localeCompare(right.packageName));
};
const createPackageContextEntry = (workspaceRootPath, packageName, dependencies = {}) => {
const {
pathImpl = path
} = dependencies;
const packageRootPath = resolvePackageRootPath(workspaceRootPath, packageName, pathImpl);
const packageJsonPath = pathImpl.join(packageRootPath, 'package.json');
const aiContextPath = pathImpl.join(packageRootPath, ...DEFAULT_PACKAGE_CONTEXT_RELATIVE_PATH);
const packageJson = readJsonFile(packageJsonPath, {}, dependencies);
const aiContextText = readTextFile(aiContextPath, dependencies);
if (aiContextText === null) {
return {
context: null,
contextBytes: 0,
contextChecksum: null,
contextPath: aiContextPath,
guides: null,
guidesBytes: 0,
guidesChecksum: null,
guidesPath: null,
packageJson,
packageName,
symbols: null,
symbolsBytes: 0,
symbolsChecksum: null,
symbolsPath: null
};
}
const aiGuidesPath = pathImpl.join(packageRootPath, ...DEFAULT_PACKAGE_GUIDES_RELATIVE_PATH);
const aiGuidesText = readTextFile(aiGuidesPath, dependencies);
const aiSymbolsPath = pathImpl.join(packageRootPath, ...DEFAULT_PACKAGE_SYMBOLS_RELATIVE_PATH);
const aiSymbolsText = readTextFile(aiSymbolsPath, dependencies);
return {
context: parseJsonText(aiContextPath, aiContextText),
contextBytes: getUtf8ByteLength(aiContextText),
contextChecksum: createChecksum(aiContextText),
contextPath: aiContextPath,
guides: aiGuidesText === null ? null : parseJsonText(aiGuidesPath, aiGuidesText),
guidesBytes: aiGuidesText === null ? 0 : getUtf8ByteLength(aiGuidesText),
guidesChecksum: aiGuidesText === null ? null : createChecksum(aiGuidesText),
guidesPath: aiGuidesText === null ? null : aiGuidesPath,
packageJson,
packageName,
symbols: aiSymbolsText === null ? null : parseJsonText(aiSymbolsPath, aiSymbolsText),
symbolsBytes: aiSymbolsText === null ? 0 : getUtf8ByteLength(aiSymbolsText),
symbolsChecksum: aiSymbolsText === null ? null : createChecksum(aiSymbolsText),
symbolsPath: aiSymbolsText === null ? null : aiSymbolsPath
};
};
export const createLockComparison = lockData => ({
framework: lockData?.framework ?? null,
sharedPackage: {
checksum: lockData?.sharedPackage?.checksum ?? null,
name: lockData?.sharedPackage?.name ?? null,
version: lockData?.sharedPackage?.version ?? null
},
packages: Array.isArray(lockData?.packages) ? [...lockData.packages].map(entry => ({
checksum: entry?.checksum ?? null,
guidesChecksum: entry?.guidesChecksum ?? null,
guidesManifestPath: entry?.guidesManifestPath ?? null,
name: entry?.name ?? null,
symbolsChecksum: entry?.symbolsChecksum ?? null,
symbolsManifestPath: entry?.symbolsManifestPath ?? null,
version: entry?.version ?? null
})).sort((left, right) => left.name.localeCompare(right.name)) : [],
instructions: Array.isArray(lockData?.generatedFiles) ? lockData.generatedFiles.filter(entry => entry?.path).map(entry => ({
checksum: entry?.checksum ?? null,
path: entry.path
})).sort((left, right) => left.path.localeCompare(right.path)) : []
});
export const normalizeAtlasAiRefreshMode = value => {
const normalizedValue = normalizeOptionalString(value)?.toLowerCase();
if (normalizedValue && START_AI_REFRESH_MODES.has(normalizedValue)) {
return normalizedValue;
}
return DEFAULT_START_AI_REFRESH_MODE;
};
export const resolveAtlasAiContextState = (options = {}, dependencies = {}, cwd = process.cwd()) => {
const {
pathImpl = path
} = dependencies;
const consumerPackageJsonPath = pathImpl.join(cwd, 'package.json');
const consumerPackage = readJsonFile(consumerPackageJsonPath, {}, dependencies);
const sharedPackageName = normalizeOptionalString(options.sharedPackage) ?? DEFAULT_SHARED_PACKAGE_NAME;
const workspaceRootPaths = resolveWorkspaceRootPaths(cwd, options, dependencies);
const workspacePackageManifestPaths = resolveWorkspacePackageManifestPaths(cwd, workspaceRootPaths, dependencies);
const sharedPackageLocation = resolveSharedPackageLocation(cwd, sharedPackageName, workspaceRootPaths, dependencies);
const {
sharedManifestPath,
sharedManifestText,
sharedPackageRootPath
} = sharedPackageLocation;
const sharedPackageJsonPath = pathImpl.join(sharedPackageRootPath, 'package.json');
const sharedManifest = parseJsonText(sharedManifestPath, sharedManifestText);
const sharedPackageJson = readJsonFile(sharedPackageJsonPath, {
allowMissing: true
}, dependencies);
const sharedPackageVersion = normalizeOptionalString(sharedManifest?.package?.version) ?? normalizeOptionalString(sharedPackageJson?.version) ?? null;
const supportedPackagePolicies = createSupportedPackagePolicies(sharedManifest.supportedPackages);
const supportedPackageNames = new Set(supportedPackagePolicies.map(policy => policy.name));
const installedAtlasPackageEntries = listInstalledAtlasPackageEntries(workspaceRootPaths, dependencies).filter(entry => entry.packageName !== sharedPackageName);
const installedAtlasPackages = installedAtlasPackageEntries.map(entry => entry.packageName);
const targetPackageEntries = supportedPackageNames.size > 0 ? installedAtlasPackageEntries.filter(entry => supportedPackageNames.has(entry.packageName)) : installedAtlasPackageEntries;
const unsupportedInstalledPackages = supportedPackageNames.size > 0 ? installedAtlasPackageEntries.filter(entry => !supportedPackageNames.has(entry.packageName)).map(entry => entry.packageName) : [];
const packageContexts = [];
const missingContexts = [];
for (const packageName of targetPackageEntries) {
const packageEntry = createPackageContextEntry(packageName.workspaceRootPath ?? cwd, packageName.packageName ?? packageName, dependencies);
const relativeContextPath = normalizePathSeparators(pathImpl.relative(cwd, packageEntry.contextPath));
if (packageEntry.context === null) {
missingContexts.push({
expectedPath: relativeContextPath,
name: packageEntry.packageName,
version: packageEntry.packageJson?.version ?? null
});
continue;
}
packageContexts.push({
checksum: packageEntry.contextChecksum,
context: packageEntry.context,
contextBytes: packageEntry.contextBytes,
guides: packageEntry.guides,
guidesBytes: packageEntry.guidesBytes,
guidesChecksum: packageEntry.guidesChecksum,
guidesManifestPath: packageEntry.guidesPath === null ? null : normalizePathSeparators(pathImpl.relative(cwd, packageEntry.guidesPath)),
manifestPath: relativeContextPath,
name: packageEntry.packageName,
symbols: packageEntry.symbols,
symbolsBytes: packageEntry.symbolsBytes,
symbolsChecksum: packageEntry.symbolsChecksum,
symbolsManifestPath: packageEntry.symbolsPath === null ? null : normalizePathSeparators(pathImpl.relative(cwd, packageEntry.symbolsPath)),
version: packageEntry.packageJson?.version ?? packageEntry.context?.package?.version ?? null
});
}
packageContexts.sort((left, right) => left.name.localeCompare(right.name));
missingContexts.sort((left, right) => left.name.localeCompare(right.name));
const sharedAgentRelativePaths = getSharedAgentRelativePaths(sharedManifest);
const sharedSkillRelativePaths = getSharedSkillRelativePaths(sharedManifest);
const sharedAgentPaths = sharedAgentRelativePaths.map(agentPath => normalizePathSeparators(pathImpl.relative(cwd, pathImpl.join(sharedPackageRootPath, agentPath))));
const sharedSkillPaths = sharedSkillRelativePaths.map(skillPath => normalizePathSeparators(pathImpl.relative(cwd, pathImpl.join(sharedPackageRootPath, skillPath))));
return {
consumerPackage,
installedAtlasPackages,
missingContexts,
packageContexts,
sharedCopilotTemplatePath: normalizePathSeparators(pathImpl.relative(cwd, pathImpl.join(sharedPackageRootPath, DEFAULT_SHARED_COPILOT_TEMPLATE_PATH))),
supportedPackagePolicies,
workspacePackageManifestPaths,
sharedAgentPath: sharedAgentPaths[0],
sharedAgentPaths,
sharedManifest,
sharedManifestChecksum: createChecksum(sharedManifestText),
sharedManifestPath: normalizePathSeparators(pathImpl.relative(cwd, sharedManifestPath)),
sharedPackageName,
sharedPackageVersion,
sharedSkillPaths,
unsupportedInstalledPackages
};
};
export const createAtlasAiCopilotInstructions = (state, outputPaths, dependencies = {}, cwd = process.cwd()) => {
const {
pathImpl = path
} = dependencies;
const workspaceManifestLines = state.workspacePackageManifestPaths.length > 0 ? state.workspacePackageManifestPaths.map(entry => ` - \`${entry}\``) : [' - `package.json`'];
const localSpecialistAgentLines = outputPaths.relativeAgentPaths.slice(1).map(entry => ` - \`${entry}\``);
const localSkillLines = outputPaths.relativeSkillPaths.map(entry => ` - \`${entry}\``);
const overlayLines = [' - `.github/instructions/project.instructions.md`', ' - `.github/agents/project.agent.md`'];
const installedPackageLines = state.packageContexts.length > 0 ? state.packageContexts.map(entry => ` - \`${entry.name}\``) : [' - No installed Atlas packages with local AI manifests were discovered.'];
const sharedAgentLines = state.sharedAgentPaths.map(entry => ` - \`${entry}\``);
const sharedSkillLines = state.sharedSkillPaths.map(entry => ` - \`${entry}\``);
const missingManifestLines = state.missingContexts.map(entry => `- ${entry.name}: expected ${entry.expectedPath}`);
const templateText = readTextFile(pathImpl.resolve(cwd, state.sharedCopilotTemplatePath), dependencies);
if (templateText === null) {
throw new Error(`Atlas AI shared Copilot instructions template is missing at ${state.sharedCopilotTemplatePath}. ` + 'Reinstall or rebuild the shared Atlas AI package before running this command.');
}
let stepNumber = 1;
const workspaceManifestStep = `${stepNumber++}. Read the workspace package manifests that define Atlas dependencies:`;
const snapshotStep = `${stepNumber++}. If present, read \`${outputPaths.relativeSnapshotPath}\` first as the committed, hosted-agent-safe Atlas semantic snapshot.`;
const leadAgentStep = `${stepNumber++}. Read the generated local Atlas lead agent:`;
const overlaySection = [`${stepNumber++}. If present, read the repo-owned Atlas overlay files:`, ...overlayLines, ''].join('\n');
const specialistAgentsSection = localSpecialistAgentLines.length > 0 ? [`${stepNumber++}. Read the generated local Atlas specialist agents when relevant:`, ...localSpecialistAgentLines, ''].join('\n') : '';
const skillsSection = localSkillLines.length > 0 ? ['If present, prefer the generated local Atlas workflow skills when the task matches them:', ...localSkillLines, ''].join('\n') : '';
const packageDrillDownStep = `${stepNumber++}. If the snapshot points to a relevant Atlas package, drill into that package only as needed using its local \`dist/ai-context.json\`, \`dist/ai-guides.json\`, and \`dist/ai-symbols.json\` artifacts.`;
const lockFileStep = `${stepNumber++}. Read \`${outputPaths.relativeLockFilePath}\` only when you need exact installed manifest paths, drift verification, or regeneration troubleshooting.`;
const sharedPackageAssetsStep = `${stepNumber++}. For Atlas framework provenance and regeneration troubleshooting, read the shared Atlas AI package assets:`;
const missingManifestSection = missingManifestLines.length > 0 ? ['', '## Missing Atlas AI Manifests', '', ...missingManifestLines].join('\n') : '';
return `${replaceTemplateVariables(templateText, {
INSTALLED_PACKAGE_LINES: installedPackageLines.join('\n'),
LEAD_AGENT_LINE: ` - \`${outputPaths.relativeAgentPath}\``,
LEAD_AGENT_STEP: leadAgentStep,
LOCK_FILE_STEP: lockFileStep,
MISSING_MANIFEST_SECTION: missingManifestSection,
PACKAGE_DRILL_DOWN_STEP: packageDrillDownStep,
SHARED_AGENT_LINES: sharedAgentLines.join('\n'),
SHARED_SKILL_LINES: sharedSkillLines.join('\n'),
SHARED_MANIFEST_PATH: state.sharedManifestPath,
SHARED_PACKAGE_ASSETS_STEP: sharedPackageAssetsStep,
SKILLS_SECTION: skillsSection,
SNAPSHOT_STEP: snapshotStep,
SPECIALIST_AGENTS_SECTION: specialistAgentsSection,
OVERLAY_SECTION: overlaySection,
WORKSPACE_MANIFEST_LINES: workspaceManifestLines.join('\n'),
WORKSPACE_MANIFEST_STEP: workspaceManifestStep
})}\n`;
};
const getPackageMaturityRank = maturity => {
const normalizedMaturity = normalizeOptionalString(maturity);
return ATLAS_AI_MATURITY_ORDER.indexOf(normalizedMaturity);
};
const satisfiesMinimumMaturity = (currentMaturity, minimumMaturity) => {
if (!normalizeOptionalString(minimumMaturity)) {
return true;
}
const minimumRank = getPackageMaturityRank(minimumMaturity);
const currentRank = getPackageMaturityRank(currentMaturity);
if (minimumRank === -1 || currentRank === -1) {
return false;
}
return currentRank >= minimumRank;
};
const hasSnapshotSymbolEnrichment = symbol => normalizeOptionalString(symbol?.purpose) || hasSnapshotArrayValues(symbol?.useWhen) || hasSnapshotArrayValues(symbol?.avoidWhen) || hasSnapshotArrayValues(symbol?.preferredFor) || hasSnapshotArrayValues(symbol?.notFor) || hasSnapshotArrayValues(symbol?.relatedSymbols) || hasSnapshotArrayValues(symbol?.composesWith) || hasSnapshotArrayValues(symbol?.owners) || hasSnapshotArrayValues(symbol?.audience) || symbol?.canonical === true || normalizeOptionalString(symbol?.reviewStatus) || normalizeOptionalString(symbol?.status);
const isHighSignalSnapshotKind = symbol => !['type', 'enum', 'namespace'].includes(normalizeOptionalString(symbol?.kind) ?? '');
const hasMeaningfulSnapshotSummary = symbol => normalizeOptionalString(symbol?.description) && !isGenericSnapshotSymbolSummary(symbol.description);
const getSnapshotSymbolTrustScore = symbol => {
let trustScore = 0;
if (normalizeOptionalString(symbol?.reviewStatus) === 'reviewed') {
trustScore += 8;
}
if (normalizeOptionalString(symbol?.status) === 'stable') {
trustScore += 4;
}
if (symbol?.canonical === true) {
trustScore += 2;
}
return trustScore;
};
const sortSnapshotSymbolsForSelection = symbolPool => (Array.isArray(symbolPool) ? symbolPool : []).map((symbol, index) => ({
index,
symbol
})).sort((left, right) => {
const trustScoreDifference = getSnapshotSymbolTrustScore(right.symbol) - getSnapshotSymbolTrustScore(left.symbol);
if (trustScoreDifference !== 0) {
return trustScoreDifference;
}
return left.index - right.index;
}).map(entry => entry.symbol);
const selectSnapshotSymbols = (symbols, limit = SNAPSHOT_SYMBOL_LIMIT_PER_ENTRYPOINT, options = {}) => {
if (!Array.isArray(symbols) || symbols.length === 0) {
return [];
}
const {
allowMeaningfulSummaryFallback = true
} = options;
const selectedSymbols = [];
const selectedSymbolKeys = new Set();
const addSymbolPool = symbolPool => {
for (const symbol of sortSnapshotSymbolsForSelection(symbolPool)) {
const symbolKey = createSnapshotSymbolKey(symbol);
if (!symbolKey || selectedSymbolKeys.has(symbolKey)) {
continue;
}
selectedSymbolKeys.add(symbolKey);
selectedSymbols.push(symbol);
if (selectedSymbols.length >= limit) {
return;
}
}
};
addSymbolPool(symbols.filter(symbol => symbol?.classification === 'atlas-owned' && isHighSignalSnapshotKind(symbol) && hasSnapshotSymbolEnrichment(symbol)));
if (selectedSymbols.length > 0) {
return selectedSymbols.slice(0, limit);
}
if (!allowMeaningfulSummaryFallback) {
return [];
}
addSymbolPool(symbols.filter(symbol => symbol?.classification === 'atlas-owned' && isHighSignalSnapshotKind(symbol) && hasMeaningfulSnapshotSummary(symbol)));
addSymbolPool(symbols.filter(symbol => isHighSignalSnapshotKind(symbol) && hasMeaningfulSnapshotSummary(symbol)));
return selectedSymbols.slice(0, limit);
};
const createSnapshotSelectedSymbolsByEntrypoint = (symbolsArtifact, options = {}) => {
const selectedSymbolsByEntrypoint = new Map();
const entrypoints = Array.isArray(symbolsArtifact?.entrypoints) ? symbolsArtifact.entrypoints : [];
for (const entrypoint of entrypoints) {
const entrypointPath = normalizeOptionalString(entrypoint?.path);
if (!entrypointPath) {
continue;
}
selectedSymbolsByEntrypoint.set(entrypointPath, selectSnapshotSymbols(entrypoint?.symbols, SNAPSHOT_SYMBOL_LIMIT_PER_ENTRYPOINT, options));
}
return selectedSymbolsByEntrypoint;
};
const createSnapshotEntrypoints = (context, symbolsArtifact, selectedSymbolsByEntrypoint) => {
const snapshotEntrypoints = [];
const seenEntrypointPaths = new Set();
const addSnapshotEntrypoint = entrypoint => {
const entrypointPath = normalizeOptionalString(entrypoint?.path);
if (!entrypointPath || seenEntrypointPaths.has(entrypointPath)) {
return;
}
const topSymbolIds = (selectedSymbolsByEntrypoint.get(entrypointPath) ?? []).map(symbol => createSnapshotSymbolKey(symbol, entrypointPath)).filter(Boolean);
snapshotEntrypoints.push({
path: entrypointPath,
...(normalizeOptionalString(entrypoint?.purpose) ? {
purpose: entrypoint.purpose
} : {}),
...(normalizeOptionalString(entrypoint?.sourcePath) ? {
sourcePath: entrypoint.sourcePath
} : {}),
...(typeof entrypoint?.symbolCount === 'number' ? {
symbolCount: entrypoint.symbolCount
} : {}),
...(hasSnapshotArrayValues(entrypoint?.primarySymbolGroups) ? {
primarySymbolGroups: [...entrypoint.primarySymbolGroups]
} : {}),
...(topSymbolIds.length ? {
topSymbolIds
} : {})
});
seenEntrypointPaths.add(entrypointPath);
};
for (const entrypoint of Array.isArray(context?.entrypoints) ? context.entrypoints : []) {
addSnapshotEntrypoint(entrypoint);
}
for (const entrypoint of Array.isArray(symbolsArtifact?.entrypoints) ? symbolsArtifact.entrypoints : []) {
addSnapshotEntrypoint(entrypoint);
}
return snapshotEntrypoints;
};
const createSnapshotSelectedGuides = guidesArtifact => {
if (!Array.isArray(guidesArtifact?.guides) || guidesArtifact.guides.length === 0) {
return [];
}
const selectedGuides = [];
const selectedGuideIds = new Set();
for (const guide of guidesArtifact.guides) {
const guideId = normalizeOptionalString(guide?.id);
if (!guideId || selectedGuideIds.has(guideId)) {
continue;
}
selectedGuideIds.add(guideId);
selectedGuides.push(createSnapshotSelectedGuideSummary(guide));
if (selectedGuides.length >= SNAPSHOT_GUIDE_LIMIT_PER_PACKAGE) {
break;
}
}
return selectedGuides;
};
const createSnapshotSelectedSymbols = (snapshotEntrypoints, selectedSymbolsByEntrypoint) => {
const selectedSymbols = [];
const selectedSymbolKeys = new Set();
const selectedSemanticKeys = new Set();
const createSnapshotSemanticSymbolKey = symbol => [normalizeOptionalString(symbol?.publicName) ?? normalizeOptionalString(symbol?.name), normalizeOptionalString(symbol?.kind), normalizeOptionalString(symbol?.sourcePath)].filter(Boolean).join(':');
for (const entrypoint of snapshotEntrypoints) {
const entrypointPath = normalizeOptionalString(entrypoint?.path);
for (const symbol of selectedSymbolsByEntrypoint.get(entrypointPath) ?? []) {
const symbolKey = createSnapshotSymbolKey(symbol, entrypointPath);
const semanticKey = createSnapshotSemanticSymbolKey(symbol);
if (!symbolKey || selectedSymbolKeys.has(symbolKey)) {
continue;
}
if (semanticKey && selectedSemanticKeys.has(semanticKey)) {
continue;
}
selectedSymbolKeys.add(symbolKey);
if (semanticKey) {
selectedSemanticKeys.add(semanticKey);
}
selectedSymbols.push(createSnapshotSelectedSymbolSummary(symbol));
if (selectedSymbols.length >= SNAPSHOT_SYMBOL_LIMIT_PER_PACKAGE) {
return selectedSymbols;
}
}
}
return selectedSymbols;
};
const createSnapshotPackageMaturity = (symbolsArtifact, guidesArtifact) => {
const allGuides = Array.isArray(guidesArtifact?.guides) ? guidesArtifact.guides : [];
if (allGuides.length > 0) {
return 'guide-enriched';
}
const allSymbols = (Array.isArray(symbolsArtifact?.entrypoints) ? symbolsArtifact.entrypoints : []).flatMap(entrypoint => Array.isArray(entrypoint?.symbols) ? entrypoint.symbols : []);
return allSymbols.some(hasSnapshotSymbolEnrichment) ? 'symbol-enriched' : 'inventory-only';
};
const createAtlasAiSnapshotPackage = entry => {
const selectedGuides = createSnapshotSelectedGuides(entry.guides);
const selectedSymbolsByEntrypoint = createSnapshotSelectedSymbolsByEntrypoint(entry.symbols, {
allowMeaningfulSummaryFallback: selectedGuides.length === 0
});
const snapshotEntrypoints = createSnapshotEntrypoints(entry.context, entry.symbols, selectedSymbolsByEntrypoint);
const selectedSymbols = createSnapshotSelectedSymbols(snapshotEntrypoints, selectedSymbolsByEntrypoint);
return {
name: entry.name,
...(normalizeOptionalString(entry.version) ? {
version: entry.version
} : {}),
maturity: createSnapshotPackageMaturity(entry.symbols, entry.guides),
...(normalizeOptionalString(entry.context?.packageRole) ? {
role: entry.context.packageRole
} : {}),
...(normalizeOptionalString(entry.context?.responsibility) ? {
responsibility: entry.context.responsibility
} : {}),
...(hasSnapshotArrayValues(entry.context?.ownedSurface) ? {
ownedSurface: [...entry.context.ownedSurface]
} : {}),
...(hasSnapshotArrayValues(snapshotEntrypoints) ? {
entrypoints: snapshotEntrypoints
} : {}),
...(hasSnapshotArrayValues(selectedGuides) ? {
selectedGuides
} : {}),
...(hasSnapshotArrayValues(selectedSymbols) ? {
selectedSymbols
} : {}),
...(hasSnapshotArrayValues(entry.context?.relatedPackages) ? {
relatedPackages: entry.context.relatedPackages.map(relatedPackage => ({
name: relatedPackage.name,
relationship: relatedPackage.relationship
}))
} : {})
};
};
export const createAtlasAiSnapshotData = (state, commandName) => ({
schemaVersion: '1.0.0',
manifestType: 'atlas-consumer-ai-snapshot',
framework: 'Atlas',
generatedFrom: {
sharedPackage: `${state.sharedManifest?.package?.name ?? state.sharedPackageName}@` + `${state.sharedPackageVersion ?? 'unknown'}`,
workspaceManifests: state.workspacePackageManifestPaths.length > 0 ? [...state.workspacePackageManifestPaths] : ['package.json'],
generatedBy: commandName
},
packages: state.packageContexts.map(createAtlasAiSnapshotPackage),
...(state.missingContexts.length ? {
missingContexts: state.missingContexts.map(entry => ({
expectedPath: entry.expectedPath,
name: entry.name,
version: entry.version
}))
} : {}),
unsupportedInstalledPackages: [...state.unsupportedInstalledPackages]
});
const createAtlasAiConsumerQualityMetrics = artifacts => {
const snapshotText = createJsonText(artifacts.snapshotData);
const lockText = createJsonText(artifacts.lockData);
const selectedSymbols = (Array.isArray(artifacts.snapshotData?.packages) ? artifacts.snapshotData.packages : []).flatMap(snapshotPackage => Array.isArray(snapshotPackage?.selectedSymbols) ? snapshotPackage.selectedSymbols : []);
const rawArtifactBytes = (Array.isArray(artifacts.packageContexts) ? artifacts.packageContexts : []).reduce((totalBytes, entry) => totalBytes + (entry?.contextBytes ?? 0) + (entry?.guidesBytes ?? 0) + (entry?.symbolsBytes ?? 0), 0);
const snapshotBytes = getUtf8ByteLength(snapshotText);
const agentBytes = artifacts.agentFiles.reduce((totalBytes, agentFile) => totalBytes + getUtf8ByteLength(agentFile.content), 0);
const skillBytes = artifacts.skillFiles.reduce((totalBytes, skillFile) => totalBytes + getUtf8ByteLength(skillFile.content), 0);
return {
agentBytes,
bootstrapBytes: agentBytes + skillBytes + getUtf8ByteLength(artifacts.instructionsContent) + snapshotBytes + getUtf8ByteLength(lockText),
genericSelectedSymbolCount: selectedSymbols.filter(symbol => isGenericSnapshotSymbolSummary(symbol?.summary)).length,
instructionsBytes: getUtf8ByteLength(artifacts.instructionsContent),
lockBytes: getUtf8ByteLength(lockText),
rawArtifactBytes,
selectedGuideCount: (Array.isArray(artifacts.snapshotData?.packages) ? artifacts.snapshotData.packages : []).reduce((totalCount, snapshotPackage) => totalCount + (Array.isArray(snapshotPackage?.selectedGuides) ? snapshotPackage.selectedGuides.length : 0), 0),
selectedSymbolCount: selectedSymbols.length,
skillBytes,
snapshotBytes,
snapshotCompressionFactor: rawArtifactBytes > 0 ? rawArtifactBytes / snapshotBytes : null
};
};
const getConsumerQualityFindingSeverity = verificationPolicyMode => verificationPolicyMode === 'localDevelopment' ? 'warning' : 'error';
export const createAtlasAiConsumerQualitySummaryRows = artifacts => {
const metrics = createAtlasAiConsumerQualityMetrics(artifacts);
return [{
label: 'Bootstrap bytes',
value: `${metrics.bootstrapBytes} / ${ATLAS_AI_CONSUMER_QUALITY_CONTRACT.maxBootstrapBytes}`
}, {
label: 'Snapshot bytes',
value: `${metrics.snapshotBytes} / ${ATLAS_AI_CONSUMER_QUALITY_CONTRACT.maxSnapshotBytes}`
}, {
label: 'Generic selected symbols',
value: `${metrics.genericSelectedSymbolCount} / ` + `${ATLAS_AI_CONSUMER_QUALITY_CONTRACT.maxGenericSelectedSymbols}`
}, {
label: 'Snapshot compression',
value: metrics.snapshotCompressionFactor === null ? 'n/a' : `${metrics.snapshotCompressionFactor.toFixed(1)}x / ` + `${ATLAS_AI_CONSUMER_QUALITY_CONTRACT.minSnapshotCompressionFactor.toFixed(1)}x`
}];
};
const getPackageConsumerImpactBaseScore = maturity => {
const normalizedMaturity = normalizeOptionalString(maturity);
if (normalizedMaturity === 'inventory-only') {
return 100;
}
if (normalizedMaturity === 'symbol-enriched') {
return 50;
}
return 0;
};
const createAtlasAiPackageConsumerImpactEntries = artifacts => {
const packageContextLookup = new Map((Array.isArray(artifacts.packageContexts) ? artifacts.packageContexts : []).map(entry => [entry.name, entry]));
return (Array.isArray(artifacts.snapshotData?.packages) ? artifacts.snapshotData.packages : []).map(snapshotPackage => {
const selectedGuides = Array.isArray(snapshotPackage?.selectedGuides) ? snapshotPackage.selectedGuides : [];
const selectedSymbols = Array.isArray(snapshotPackage?.selectedSymbols) ? snapshotPackage.selectedSymbols : [];
const semanticSelectedSymbolCount = selectedSymbols.filter(hasSemanticSnapshotSelectedSymbol).length;
const packageContext = packageContextLookup.get(snapshotPackage.name);
const rawArtifactBytes = (packageContext?.contextBytes ?? 0) + (packageContext?.guidesBytes ?? 0) + (packageContext?.symbolsBytes ?? 0);
const priorityScore = getPackageConsumerImpactBaseScore(snapshotPackage.maturity) + (selectedGuides.length === 0 ? 35 : 0) + (selectedSymbols.length === 0 ? 35 : 0) + (semanticSelectedSymbolCount === 0 ? 30 : 0) + Math.max(0, selectedSymbols.length - semanticSelectedSymbolCount) * 10;
return {
maturity: snapshotPackage.maturity,
name: snapshotPackage.name,
priorityScore,
rawArtifactBytes,
selectedGuideCount: selectedGuides.length,
selectedSymbolCount: selectedSymbols.length,
semanticSelectedSymbolCount
};
}).sort((left, right) => {
if (right.priorityScore !== left.priorityScore) {
return right.priorityScore - left.priorityScore;
}
if (right.rawArtifactBytes !== left.rawArtifactBytes) {
return right.rawArtifactBytes - left.rawArtifactBytes;
}
return left.name.localeCompare(right.name);
});
};
export const createAtlasAiConsumerImpactSummaryRows = (artifacts, limit = 5) => createAtlasAiPackageConsumerImpactEntries(artifacts).filter(entry => entry.priorityScore > 0).slice(0, limit).map(entry => ({
label: entry.name,
value: `priority ${entry.priorityScore} | ` + `maturity ${entry.maturity} | ` + `semantic symbols ${entry.semanticSelectedSymbolCount}/${entry.selectedSymbolCount} | ` + `guides ${entry.selectedGuideCount} | ` + `raw ${entry.rawArtifactBytes} bytes`
}));
export const createCoverageFindings = (artifacts, options = {}) => {
const findings = {
issues: [],
records: [],
warnings: []
};
const supportedPackagePolicyLookup = createSupportedPackagePolicyLookup(artifacts.supportedPackagePolicies);
const verificationPolicyMode = resolveVerificationPolicyMode(options);
const missingRequiredArtifactsSeverity = getVerificationSeverity(artifacts.sharedManifest, verificationPolicyMode, 'missingRequiredArtifacts', 'error');
const belowMinimumMaturitySeverity = getVerificationSeverity(artifacts.sharedManifest, verificationPolicyMode, 'belowMinimumMaturity', options.strict ? 'error' : 'warning');
const unsupportedInstalledPackagesSeverity = getVerificationSeverity(artifacts.sharedManifest, verificationPolicyMode, 'unsupportedInstalledPackages', options.strict ? 'error' : 'warning');
const consumerQualitySeverity = getConsumerQualityFindingSeverity(verificationPolicyMode);
const consumerQualityMetrics = createAtlasAiConsumerQualityMetrics(artifacts);
const missingSymbols = artifacts.packageContexts.filter(entry => {
const policy = supportedPackagePolicyLookup.get(entry.name);
return policy?.requiredArtifacts.includes('symbols') && entry.symbols === null;
}).map(entry => entry.name);
const missingGuides = artifacts.packageContexts.filter(entry => {
const policy = supportedPackagePolicyLookup.get(entry.name);
return policy?.requiredArtifacts.includes('guides') && entry.guides === null;
}).map(entry => entry.name);
const packagesBelowMinimumMaturity = artifacts.snapshotData.packages.map(snapshotPackage => ({
minimumMaturity: supportedPackagePolicyLookup.get(snapshotPackage.name)?.minimumMaturity ?? null,
name: snapshotPackage.name,
currentMaturity: snapshotPackage.maturity
})).filter(entry => entry.minimumMaturity && !satisfiesMinimumMaturity(entry.currentMaturity, entry.minimumMaturity));
if (artifacts.missingContexts.length > 0) {
pushVerificationFinding(findings, missingRequiredArtifactsSeverity, `Installed Atlas packages are missing dist/ai-context.json: ${artifacts.missingContexts.map(entry => entry.name).join(', ')}`, {
code: 'missing-ai-context',
items: artifacts.missingContexts.map(entry => entry.name),
title: 'Installed Atlas packages are missing dist/ai-context.json'
});
}
if (missingSymbols.length > 0) {
pushVerificationFinding(findings, missingRequiredArtifactsSeverity, `Installed Atlas packages are missing dist/ai-symbols.json: ${missingSymbols.join(', ')}`, {
code: 'missing-ai-symbols',
items: missingSymbols,
title: 'Installed Atlas packages are missing dist/ai-symbols.json'
});
}
if (missingGuides.length > 0) {
pushVerificationFinding(findings, missingRequiredArtifactsSeverity, `Installed Atlas packages are missing dist/ai-guides.json: ${missingGuides.join(', ')}`, {
code: 'missing-ai-guides',
items: missingGuides,
title: 'Installed Atlas packages are missing dist/ai-guides.json'
});
}
if (packagesBelowMinimumMaturity.length > 0) {
pushVerificationFinding(findings, belowMinimumMaturitySeverity, `Installed Atlas packages do not meet required Atlas AI maturity: ${packagesBelowMinimumMaturity.map(entry => `${entry.name} (required: ${entry.minimumMaturity}, current: ${entry.currentMaturity})`).join(', ')}`, {
code: 'below-minimum-maturity',
items: packagesBelowMinimumMaturity.map(entry => `${entry.name} (required: ${entry.minimumMaturity}, current: ${entry.currentMaturity})`),
title: 'Installed Atlas packages do not meet required Atlas AI maturity'
});
}
if (artifacts.unsupportedInstalledPackages.length > 0) {
pushVerificationFinding(findings, unsupportedInstalledPackagesSeverity, `Installed Atlas packages are not yet covered by the shared Atlas AI manifest: ${artifacts.unsupportedInstalledPackages.join(', ')}`, {
code: 'unsupported-installed-packages',
items: artifacts.unsupportedInstalledPackages,
title: 'Installed Atlas packages are not yet covered by the shared Atlas AI manifest'
});
}
if (consumerQualityMetrics.bootstrapBytes > ATLAS_AI_CONSUMER_QUALITY_CONTRACT.maxBootstrapBytes) {
pushVerificationFinding(findings, consumerQualitySeverity, 'Generated Atlas AI bootstrap exceeds the consumer quality budget: ' + `${consumerQualityMetrics.bootstrapBytes} bytes ` + `(max ${ATLAS_AI_CONSUMER_QUALITY_CONTRACT.maxBootstrapBytes}).`);
}
if (consumerQualityMetrics.snapshotBytes > ATLAS_AI_CONSUMER_QUALITY_CONTRACT.maxSnapshotBytes) {
pushVerificationFinding(findings, consumerQualitySeverity, 'Generated Atlas AI snapshot exceeds the consumer quality budget: ' + `${consumerQualityMetrics.snapshotBytes} bytes ` + `(max ${ATLAS_AI_CONSUMER_QUALITY_CONTRACT.maxSnapshotBytes}).`);
}
if (consumerQualityMetrics.genericSelectedSymbolCount > ATLAS_AI_CONSUMER_QUALITY_CONTRACT.maxGenericSelectedSymbols) {
pushVerificationFinding(findings, consumerQualitySeverity, 'Generated Atlas AI snapshot exceeds the generic selected symbol threshold: ' + `${consumerQualityMetrics.genericSelectedSymbolCount} ` + `(max ${ATLAS_AI_CONSUMER_QUALITY_CONTRACT.maxGenericSelectedSymbols}).`);
}
if (consumerQualityMetrics.snapshotCompressionFactor !== null && consumerQualityMetrics.snapshotCompressionFactor < ATLAS_AI_CONSUMER_QUALITY_CONTRACT.minSnapshotCompressionFactor) {
pushVerificationFinding(findings, consumerQualitySeverity, 'Generated Atlas AI snapshot falls below the minimum compression threshold: ' + `${consumerQualityMetrics.snapshotCompressionFactor.toFixed(1)}x ` + `(min ${ATLAS_AI_CONSUMER_QUALITY_CONTRACT.minSnapshotCompressionFactor.toFixed(1)}x).`);
}
return findings;
};