@hone-ai/cli 1.4.0

package/lib/validate-metadata.js

@@ -0,0 +1,175 @@
+'use strict';
+/**
+ * validate-metadata.js — SC-011 (Phase 11 of SC family).
+ * Pure helper that validates a `.github/pipeline/<STORY-ID>/metadata.yml`
+ * file against the JSON schema at
+ * `enterprise-assets/.github/schema/metadata.schema.json` (canonical) or
+ * an adopter-supplied override.
+ *
+ * Implements what SC-010 §10 documented (metadata.yml as wire protocol):
+ * 3+ agents read these files; without schema validation, typos like
+ * `fixFor` vs `fix_for` silently degrade to no-op behavior.
+ *
+ * Failure modes (all return structured result; never throw):
+ *   - file missing                 → status: 'not-found' finding
+ *   - malformed YAML               → status: 'malformed-yaml' finding
+ *   - schema file missing/unparseable → status: 'schema-error' finding
+ *   - schema-validation errors     → ERROR findings, one per ajv error
+ *
+ * Pure-helper-with-injected-IO style (Category B per cli/lib/README.md):
+ *   - Reads files via fs (could be injected; kept simple for now)
+ *   - Returns { findings, summary }
+ *   - Never throws
+ *
+ * Issue: SC-011 — first JSON schema in the framework. Establishes the
+ * convention for any future schema (skill manifests, agent metadata,
+ * pipeline-config, etc.) per pipeline-integrity §15.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const KNOWN_SEVERITIES = ['ERROR', 'WARN', 'INFO'];
+
+/**
+ * Validate a metadata.yml file against a JSON schema.
+ *
+ * @param {object}  args
+ * @param {string}  args.path        path to metadata.yml
+ * @param {string}  args.schemaPath  path to JSON schema file
+ * @returns {{
+ *   findings: Array<{severity: string, code: string, path: string, message: string}>,
+ *   summary: { total: number, errors: number, warnings: number, info: number },
+ *   filePath: string,
+ * }}
+ */
+function validateMetadata({ path: filePath, schemaPath } = {}) {
+  const findings = [];
+
+  if (!filePath || typeof filePath !== 'string') {
+    return wrap([{ severity: 'ERROR', code: 'invalid-args', path: '', message: 'path is required' }]);
+  }
+  if (!schemaPath || typeof schemaPath !== 'string') {
+    return wrap([{ severity: 'ERROR', code: 'invalid-args', path: '', message: 'schemaPath is required' }]);
+  }
+
+  if (!fs.existsSync(filePath)) {
+    return wrap([{ severity: 'ERROR', code: 'file-not-found', path: filePath, message: `metadata file not found: ${filePath}` }]);
+  }
+  if (!fs.existsSync(schemaPath)) {
+    return wrap([{ severity: 'ERROR', code: 'schema-not-found', path: schemaPath, message: `schema file not found: ${schemaPath}` }]);
+  }
+
+  // Parse the schema
+  let schema;
+  try {
+    schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+  } catch (e) {
+    return wrap([{ severity: 'ERROR', code: 'schema-error', path: schemaPath, message: `cannot parse schema: ${e.message}` }]);
+  }
+
+  // Parse the metadata file. Use JSON_SCHEMA to keep ISO timestamps as strings
+  // (default schema auto-converts to Date objects, which the JSON Schema
+  // type=["string","null"] declarations reject).
+  let parsed;
+  try {
+    const yaml = require('js-yaml');
+    parsed = yaml.load(fs.readFileSync(filePath, 'utf8'), { schema: yaml.JSON_SCHEMA });
+  } catch (e) {
+    return wrap([{ severity: 'ERROR', code: 'malformed-yaml', path: filePath, message: `cannot parse YAML: ${e.message}` }]);
+  }
+
+  // Compile + validate via ajv. Use the 2020-12 entry point because the
+  // schema uses Draft 2020-12 (`$schema: .../draft/2020-12/schema`).
+  let validate;
+  try {
+    const Ajv = require('ajv/dist/2020');
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    validate = ajv.compile(schema);
+  } catch (e) {
+    return wrap([{ severity: 'ERROR', code: 'schema-error', path: schemaPath, message: `ajv compile failed: ${e.message}` }]);
+  }
+
+  const valid = validate(parsed);
+  if (!valid) {
+    for (const err of validate.errors || []) {
+      findings.push({
+        severity: 'ERROR',
+        code: err.keyword || 'validation',
+        path: err.instancePath || '/',
+        message: formatAjvError(err),
+      });
+    }
+  }
+
+  return wrap(findings, filePath);
+}
+
+function formatAjvError(err) {
+  const { keyword, instancePath, message, params } = err;
+  let detail = message || keyword;
+  if (params) {
+    if (params.missingProperty) detail = `missing required property '${params.missingProperty}'`;
+    else if (params.additionalProperty) detail = `unexpected property '${params.additionalProperty}'`;
+    else if (params.allowedValues) detail = `${message}: allowed [${params.allowedValues.join(', ')}]`;
+  }
+  return `${instancePath || '/'}: ${detail}`;
+}
+
+function wrap(findings, filePath) {
+  const summary = {
+    total: findings.length,
+    errors: findings.filter(f => f.severity === 'ERROR').length,
+    warnings: findings.filter(f => f.severity === 'WARN').length,
+    info: findings.filter(f => f.severity === 'INFO').length,
+  };
+  return { findings, summary, filePath: filePath || null };
+}
+
+/**
+ * Validate every metadata.yml under a pipeline directory.
+ *
+ * @param {object}  args
+ * @param {string}  args.repoRoot
+ * @param {string}  args.schemaPath
+ * @returns {{
+ *   files: Array<{ filePath, findings, summary }>,
+ *   summary: { total, errors, warnings, info, fileCount, errorFileCount },
+ * }}
+ */
+function validateAllMetadata({ repoRoot, schemaPath }) {
+  const pipelineDir = path.join(repoRoot, '.github/pipeline');
+  if (!fs.existsSync(pipelineDir)) {
+    return {
+      files: [],
+      summary: { total: 0, errors: 0, warnings: 0, info: 0, fileCount: 0, errorFileCount: 0 },
+    };
+  }
+  const stories = fs.readdirSync(pipelineDir).filter(d =>
+    fs.statSync(path.join(pipelineDir, d)).isDirectory()
+  );
+
+  const files = [];
+  for (const story of stories) {
+    const filePath = path.join(pipelineDir, story, 'metadata.yml');
+    if (!fs.existsSync(filePath)) continue;
+    files.push(validateMetadata({ path: filePath, schemaPath }));
+  }
+
+  const summary = {
+    total: files.reduce((s, f) => s + f.summary.total, 0),
+    errors: files.reduce((s, f) => s + f.summary.errors, 0),
+    warnings: files.reduce((s, f) => s + f.summary.warnings, 0),
+    info: files.reduce((s, f) => s + f.summary.info, 0),
+    fileCount: files.length,
+    errorFileCount: files.filter(f => f.summary.errors > 0).length,
+  };
+
+  return { files, summary };
+}
+
+module.exports = {
+  validateMetadata,
+  validateAllMetadata,
+  KNOWN_SEVERITIES,
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@hone-ai/cli",
+  "version": "1.4.0",
+  "description": "Hone AI — Enterprise SDLC Pipeline CLI",
+  "main": "hone-cli.js",
+  "bin": {
+    "hone": "./bin/hone.js"
+  },
+  "files": [
+    "bin/",
+    "hone-cli.js",
+    "lib/",
+    "!lib/*.test.js"
+  ],
+  "scripts": {
+    "test": "echo \"No tests yet\" && exit 0",
+    "link": "npm link"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "axios": "^1.6.0",
+    "commander": "^11.0.0",
+    "js-yaml": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "hone",
+    "ai",
+    "sdlc",
+    "pipeline",
+    "enterprise",
+    "developer-tools"
+  ],
+  "author": "Hone AI",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}