archgraph-argo 0.1.0

package/argo/scripts/validateSystemArchitecture.js

@@ -0,0 +1,254 @@
+const fs = require('fs');
+const path = require('path');
+
+const {
+  getArgoRoot,
+  getWorkspaceRoot,
+} = require('./argo-paths.js');
+
+const repoRoot = getWorkspaceRoot();
+const graphRelativePath = path.join('design', 'KG', 'SystemArchitecture.json');
+const graphPath = path.join(repoRoot, graphRelativePath);
+const schemaPathCandidates = [
+    path.join(getArgoRoot(), 'schema', 'SystemArchitecture.schema.json'),
+    path.join(repoRoot, '.argo', 'schema', 'SystemArchitecture.schema.json'),
+];
+
+const {
+  validateGraphSemantics,
+  validateArchiMateEndpointMatrix,
+  validateViewElementLimits,
+} = require('./graph-semantics.js');
+
+function main() {
+    const schemaPath = schemaPathCandidates.find(candidate => fs.existsSync(candidate));
+    if (!schemaPath) {
+        fail(`Schema file is missing. Checked: ${schemaPathCandidates.map(candidate => path.relative(repoRoot, candidate)).join(', ')}`);
+    }
+
+    if (!fs.existsSync(graphPath)) {
+        fail('System architecture file is missing at design/KG/SystemArchitecture.json');
+    }
+
+    const schema = parseJson(schemaPath, path.relative(repoRoot, schemaPath));
+    const document = parseJson(graphPath, 'design/KG/SystemArchitecture.json');
+    const errors = [];
+
+    validateAgainstSchema(document, schema, '#', errors, schema);
+    validateGraphSemantics(document, errors);
+    validateArchiMateEndpointMatrix(document, errors);
+    validateViewElementLimits(document, errors);
+
+    if (errors.length > 0) {
+        console.error('SystemArchitecture validation failed:');
+        for (const error of errors) {
+            console.error(`- ${error}`);
+        }
+        process.exit(1);
+    }
+
+    console.log('SystemArchitecture validation passed for: design/KG/SystemArchitecture.json');
+}
+
+function parseJson(filePath, label) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    } catch (error) {
+        fail(`Failed to parse ${label}: ${String(error)}`);
+    }
+}
+
+function validateAgainstSchema(value, schemaNode, pointer, errors, rootSchema) {
+    if (!schemaNode || typeof schemaNode !== 'object') {
+        return;
+    }
+
+    const resolvedSchema = schemaNode.$ref ? resolveRef(schemaNode.$ref, rootSchema, errors, pointer) : schemaNode;
+    if (!resolvedSchema) {
+        return;
+    }
+
+    if (resolvedSchema.const !== undefined && !isDeepStrictEqual(value, resolvedSchema.const)) {
+        errors.push(`${pointer} must equal ${JSON.stringify(resolvedSchema.const)}`);
+        return;
+    }
+
+    if (resolvedSchema.enum && !resolvedSchema.enum.some(option => isDeepStrictEqual(option, value))) {
+        errors.push(`${pointer} must be one of: ${resolvedSchema.enum.map(option => JSON.stringify(option)).join(', ')}`);
+        return;
+    }
+
+    if (resolvedSchema.type !== undefined) {
+        validateType(value, resolvedSchema.type, pointer, errors);
+        if (!typeMatches(value, resolvedSchema.type)) {
+            return;
+        }
+    }
+
+    if (typeof resolvedSchema.minLength === 'number') {
+        if (typeof value !== 'string' || value.length < resolvedSchema.minLength) {
+            errors.push(`${pointer} must be at least ${resolvedSchema.minLength} character(s) long`);
+        }
+    }
+
+    if (typeof resolvedSchema.maxLength === 'number') {
+        if (typeof value !== 'string' || value.length > resolvedSchema.maxLength) {
+            errors.push(`${pointer} must be at most ${resolvedSchema.maxLength} character(s) long`);
+        }
+    }
+
+    if (resolvedSchema.pattern) {
+        const matcher = new RegExp(resolvedSchema.pattern);
+        if (typeof value !== 'string' || !matcher.test(value)) {
+            errors.push(`${pointer} must match pattern ${JSON.stringify(resolvedSchema.pattern)}`);
+        }
+    }
+
+    if (typeof resolvedSchema.minimum === 'number') {
+        if (typeof value !== 'number' || value < resolvedSchema.minimum) {
+            errors.push(`${pointer} must be >= ${resolvedSchema.minimum}`);
+        }
+    }
+
+    if (typeof resolvedSchema.maximum === 'number') {
+        if (typeof value !== 'number' || value > resolvedSchema.maximum) {
+            errors.push(`${pointer} must be <= ${resolvedSchema.maximum}`);
+        }
+    }
+
+    if (typeof resolvedSchema.minItems === 'number') {
+        if (!Array.isArray(value) || value.length < resolvedSchema.minItems) {
+            errors.push(`${pointer} must contain at least ${resolvedSchema.minItems} item(s)`);
+        }
+    }
+
+    if (typeof resolvedSchema.maxItems === 'number') {
+        if (!Array.isArray(value) || value.length > resolvedSchema.maxItems) {
+            errors.push(`${pointer} must contain at most ${resolvedSchema.maxItems} item(s)`);
+        }
+    }
+
+    if (resolvedSchema.uniqueItems === true && Array.isArray(value)) {
+        const seen = new Set();
+        value.forEach((entry, index) => {
+            const serialized = JSON.stringify(entry);
+            if (seen.has(serialized)) {
+                errors.push(`${pointer}[${index}] must be unique within ${pointer}`);
+            } else {
+                seen.add(serialized);
+            }
+        });
+    }
+
+    if (resolvedSchema.type === 'object') {
+        validateObject(value, resolvedSchema, pointer, errors, rootSchema);
+        return;
+    }
+
+    if (resolvedSchema.type === 'array') {
+        validateArray(value, resolvedSchema, pointer, errors, rootSchema);
+    }
+}
+
+function validateObject(value, schemaNode, pointer, errors, rootSchema) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return;
+    }
+
+    const properties = schemaNode.properties || {};
+    const required = Array.isArray(schemaNode.required) ? schemaNode.required : [];
+
+    for (const key of required) {
+        if (!(key in value)) {
+            errors.push(`${pointer} is missing required property '${key}'`);
+        }
+    }
+
+    if (schemaNode.additionalProperties === false) {
+        for (const key of Object.keys(value)) {
+            if (!(key in properties)) {
+                errors.push(`${pointer} contains unsupported property '${key}'`);
+            }
+        }
+    }
+
+    for (const [key, propertySchema] of Object.entries(properties)) {
+        if (key in value) {
+            validateAgainstSchema(value[key], propertySchema, `${pointer}.${key}`, errors, rootSchema);
+        }
+    }
+}
+
+function validateArray(value, schemaNode, pointer, errors, rootSchema) {
+    if (!Array.isArray(value)) {
+        return;
+    }
+
+    if (schemaNode.items) {
+        value.forEach((entry, index) => {
+            validateAgainstSchema(entry, schemaNode.items, `${pointer}[${index}]`, errors, rootSchema);
+        });
+    }
+}
+
+function validateType(value, expectedType, pointer, errors) {
+    if (!typeMatches(value, expectedType)) {
+        const printableType = Array.isArray(expectedType) ? expectedType.join(' or ') : expectedType;
+        errors.push(`${pointer} must be of type ${printableType}`);
+    }
+}
+
+function typeMatches(value, expectedType) {
+    if (Array.isArray(expectedType)) {
+        return expectedType.some(candidate => typeMatches(value, candidate));
+    }
+
+    switch (expectedType) {
+        case 'object':
+            return value !== null && typeof value === 'object' && !Array.isArray(value);
+        case 'array':
+            return Array.isArray(value);
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value);
+        case 'integer':
+            return typeof value === 'number' && Number.isInteger(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'null':
+            return value === null;
+        default:
+            return true;
+    }
+}
+
+function resolveRef(ref, rootSchema, errors, pointer) {
+    if (!ref.startsWith('#/')) {
+        errors.push(`${pointer} uses unsupported $ref '${ref}'`);
+        return undefined;
+    }
+
+    const segments = ref.slice(2).split('/');
+    let current = rootSchema;
+    for (const segment of segments) {
+        if (!current || typeof current !== 'object' || !(segment in current)) {
+            errors.push(`${pointer} references missing schema path '${ref}'`);
+            return undefined;
+        }
+        current = current[segment];
+    }
+
+    return current;
+}
+
+function isDeepStrictEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function fail(message) {
+    console.error(`SystemArchitecture validation failed: ${message}`);
+    process.exit(1);
+}
+
+main();

package/argo/scripts/validateTraceProposal.js

@@ -0,0 +1,181 @@
+const fs = require('fs');
+const path = require('path');
+
+const {
+  getArgoRoot,
+  getWorkspaceRoot,
+} = require('./argo-paths.js');
+
+const repoRoot = getWorkspaceRoot();
+const DEFAULT_PROPOSAL_PATH = 'design/KG/ImplementationToIntentTraceProposal.json';
+const TRACE_PROPOSAL_SCHEMA_PATH = '.argo/schema/ImplementationToIntentTraceProposal.schema.json';
+
+function main() {
+    const proposalPath = process.argv[2] || DEFAULT_PROPOSAL_PATH;
+    const errors = validateTraceProposal(proposalPath);
+
+    if (errors.length > 0) {
+        console.error('Trace proposal validation failed:');
+        for (const error of errors) {
+            console.error(`- ${error}`);
+        }
+        process.exit(1);
+    }
+
+    console.log(`Trace proposal validation passed for: ${proposalPath}`);
+}
+
+function resolveSchemaAbsolutePath(schemaPath) {
+    const bundledCandidate = path.join(getArgoRoot(), 'schema', path.basename(schemaPath));
+    if (fs.existsSync(bundledCandidate)) {
+        return bundledCandidate;
+    }
+    return path.join(repoRoot, schemaPath);
+}
+
+function validateTraceProposal(proposalPath) {
+    const errors = [];
+    const schemaAbsolutePath = resolveSchemaAbsolutePath(TRACE_PROPOSAL_SCHEMA_PATH);
+    if (!fs.existsSync(schemaAbsolutePath)) {
+        errors.push(`schema file is missing at ${TRACE_PROPOSAL_SCHEMA_PATH}`);
+        return errors;
+    }
+
+    const proposalAbsolutePath = path.join(repoRoot, proposalPath.replace(/[\\/]+/g, path.sep));
+    if (!fs.existsSync(proposalAbsolutePath)) {
+        errors.push(`proposal file is missing at ${proposalPath}`);
+        return errors;
+    }
+
+    const document = readJson(proposalAbsolutePath, proposalPath, errors);
+    if (!document) {
+        return errors;
+    }
+
+    requireExact(document, 'proposalType', 'implementation-to-intent-trace', errors, proposalPath);
+    requireString(document, 'generatedAt', errors, proposalPath);
+    requireExact(document, 'sourceAgent', 'ImplementationDesign', errors, proposalPath);
+    requireExact(document, 'targetAgent', 'IntentionDesign', errors, proposalPath);
+    requireExact(document, 'lifecycle', 'temporary-trace-proposal', errors, proposalPath);
+
+    const graphPath = requireString(document, 'sourceIntentGraphPath', errors, proposalPath);
+    if (graphPath) {
+        ensureRepoPathExists(graphPath, `${proposalPath}.sourceIntentGraphPath`, errors);
+    }
+
+    const implementationContracts = requireStringArray(document, 'implementationContracts', true, errors, proposalPath);
+    if (Array.isArray(implementationContracts)) {
+        implementationContracts.forEach((contractPath, index) => {
+            ensureRepoPathExists(contractPath, `${proposalPath}.implementationContracts[${index}]`, errors);
+        });
+    }
+
+    const anchorProposals = requireArray(document, 'anchorProposals', true, errors, proposalPath);
+    if (Array.isArray(anchorProposals)) {
+        anchorProposals.forEach((anchor, index) => validateAnchorProposal(anchor, `${proposalPath}.anchorProposals[${index}]`, errors));
+    }
+
+    return errors;
+}
+
+function validateAnchorProposal(anchor, prefix, errors) {
+    requireString(anchor, 'intentElementId', errors, prefix);
+    requireString(anchor, 'implementationElementName', errors, prefix);
+    const implementationElementKind = requireString(anchor, 'implementationElementKind', errors, prefix);
+    if (implementationElementKind && ![
+        'stable-directory',
+        'contract-file',
+        'explicit-test-entry',
+        'critical-guardrail',
+        'runtime-component',
+        'schema-contract',
+        'mcp-tool',
+        'command',
+    ].includes(implementationElementKind)) {
+        errors.push(`${prefix}.implementationElementKind has unsupported value '${implementationElementKind}'`);
+    }
+
+    const implementsType = requireString(anchor, 'implementsType', errors, prefix);
+    if (implementsType && !['direct', 'indirect'].includes(implementsType)) {
+        errors.push(`${prefix}.implementsType must be 'direct' or 'indirect'`);
+    }
+
+    requireString(anchor, 'tracePurpose', errors, prefix);
+    const contractPaths = requireStringArray(anchor, 'contractPaths', true, errors, prefix);
+    if (Array.isArray(contractPaths)) {
+        contractPaths.forEach((contractPath, index) => {
+            ensureRepoPathExists(contractPath, `${prefix}.contractPaths[${index}]`, errors);
+        });
+    }
+    const contextEntryPoints = requireStringArray(anchor, 'contextEntryPoints', true, errors, prefix);
+    if (Array.isArray(contextEntryPoints)) {
+        contextEntryPoints.forEach((entryPoint, index) => {
+            ensureRepoPathExists(entryPoint, `${prefix}.contextEntryPoints[${index}]`, errors);
+        });
+    }
+    requireStringArray(anchor, 'excludedDetails', true, errors, prefix);
+}
+
+function readJson(filePath, label, errors) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8').replace(/^\uFEFF/, ''));
+    } catch (error) {
+        errors.push(`failed to parse ${label}: ${String(error)}`);
+        return undefined;
+    }
+}
+
+function requireExact(object, key, expectedValue, errors, prefix) {
+    const value = requireString(object, key, errors, prefix);
+    if (value && value !== expectedValue) {
+        errors.push(`${prefix}.${key} must be '${expectedValue}'`);
+    }
+}
+
+function requireString(object, key, errors, prefix) {
+    if (!object || typeof object[key] !== 'string' || object[key].trim() === '') {
+        errors.push(`${prefix}.${key} must be a non-empty string`);
+        return undefined;
+    }
+    return object[key];
+}
+
+function requireArray(object, key, mustHaveItems, errors, prefix) {
+    if (!object || !Array.isArray(object[key])) {
+        errors.push(`${prefix}.${key} must be an array`);
+        return undefined;
+    }
+    if (mustHaveItems && object[key].length === 0) {
+        errors.push(`${prefix}.${key} must not be empty`);
+    }
+    return object[key];
+}
+
+function requireStringArray(object, key, mustHaveItems, errors, prefix) {
+    const value = requireArray(object, key, mustHaveItems, errors, prefix);
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    value.forEach((entry, index) => {
+        if (typeof entry !== 'string' || entry.trim() === '') {
+            errors.push(`${prefix}.${key}[${index}] must be a non-empty string`);
+        }
+    });
+    return value;
+}
+
+function ensureRepoPathExists(relativePath, label, errors) {
+    const normalized = relativePath.replace(/[\\/]+/g, path.sep);
+    const absolutePath = path.join(repoRoot, normalized);
+    if (!fs.existsSync(absolutePath)) {
+        errors.push(`${label} points to a missing path: ${relativePath}`);
+    }
+}
+
+if (require.main === module) {
+    main();
+}
+
+module.exports = {
+    validateTraceProposal,
+};