hive-lite 0.1.8 → 0.2.0

package/src/lib/health.js

@@ -59,6 +59,13 @@ function patternFrom(value) {
   return normalizePath((value.pattern || value.path || '').trim());
 }
 
+function arrayFrom(value) {
+  if (Array.isArray(value)) return value.map((item) => String(item || '')).filter(Boolean);
+  if (value == null || value === '') return [];
+  if (typeof value === 'object') return [];
+  return [String(value)];
+}
+
 function readYamlHealth(root, name, fallback, findings) {
   const file = mapFile(root, name);
   if (!exists(file)) {
@@ -440,6 +447,206 @@ function rawScope(area) {
   };
 }
 
+function flattenReferenceValues(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value;
+  if (typeof value === 'object' && (value.path || value.pattern)) return [value];
+  if (typeof value === 'object') return Object.values(value).flatMap((item) => flattenReferenceValues(item));
+  return [value];
+}
+
+function readableReferences(area) {
+  const scope = area.scope || {};
+  return flattenReferenceValues(scope.readable_reference || area.readable_reference || [])
+    .map((item) => ({
+      path: patternFrom(item),
+      peerIdentity: item && typeof item === 'object' ? item.peer_identity || item.peerIdentity || item.provider || null : null,
+      artifact: item && typeof item === 'object' ? item.artifact || item.artifact_family || item.artifactFamily || null : null,
+    }))
+    .filter((item) => item.path);
+}
+
+function configuredArtifactFamilies(area) {
+  const raw = area && area.artifact_families ? area.artifact_families : null;
+  if (!raw) return [];
+  if (Array.isArray(raw)) {
+    return raw.map((item) => ({
+      id: item.id || item.name || '',
+      createRequires: arrayFrom(item.create_requires || item.createRequires),
+      hooks: arrayFrom(item.hooks),
+    })).filter((item) => item.id);
+  }
+  return Object.entries(raw).map(([id, value]) => ({
+    id,
+    createRequires: arrayFrom(value && (value.create_requires || value.createRequires)),
+    hooks: arrayFrom(value && value.hooks),
+  }));
+}
+
+function configuredPeerFileTemplateCount(area) {
+  const raw = area && (area.peer_file_templates || area.peerFileTemplates) ? area.peer_file_templates || area.peerFileTemplates : null;
+  if (!raw) return 0;
+  if (Array.isArray(raw)) return raw.length;
+  return Object.keys(raw).length;
+}
+
+function patternArtifactMatches(item, artifact) {
+  if (!artifact) return false;
+  return item.artifact === artifact || item.artifactFamily === artifact || item.artifact_family === artifact;
+}
+
+function areaLooksPeerBased(area) {
+  const text = [
+    area.id,
+    area.name,
+    area.description,
+    ...(area.aliases || []),
+    ...(area.concepts || []),
+  ].filter(Boolean).join(' ').toLowerCase();
+  return /\b(provider|proxy|adapter|integration|connector|plugin|peer)\b/.test(text)
+    || /提供商|代理|适配器|集成|连接器|插件/.test(text);
+}
+
+function rawWritableCreatePatterns(area) {
+  const scope = area.scope || {};
+  return scope.writable_create_patterns || [];
+}
+
+function validateCreatePatternMetadata(area, findings) {
+  for (const value of rawWritableCreatePatterns(area)) {
+    const pattern = patternFrom(value);
+    if (!pattern || typeof value !== 'object') {
+      addFinding(findings, {
+        severity: 'warning',
+        code: 'CREATE_PATTERN_METADATA_INCOMPLETE',
+        areaId: area.id,
+        field: field(area.id, 'scope.writable_create_patterns'),
+        message: `Create pattern uses shorthand without operation, artifact, or intent metadata: ${pattern || '(missing pattern)'}.`,
+        impact: 'writePlan can infer a create permission, but the map cannot explain which artifact and intent this permission certifies.',
+        fix: 'Convert this to an object with pattern, artifact, operations: [create_file], and intent_kinds.',
+      });
+      continue;
+    }
+    const operations = arrayFrom(value.operations || value.operation);
+    const intentKinds = arrayFrom(value.intent_kinds || value.intentKinds);
+    if (!operations.includes('create_file')) {
+      addFinding(findings, {
+        severity: 'warning',
+        code: 'CREATE_PATTERN_OPERATION_UNSPECIFIED',
+        areaId: area.id,
+        field: field(area.id, 'scope.writable_create_patterns.operations'),
+        message: `Create pattern does not explicitly declare the create_file operation: ${pattern}.`,
+        impact: 'Required write coverage is less explainable and future certificate output may be ambiguous.',
+        fix: 'Add operations: [create_file].',
+      });
+    }
+    if (!value.artifact && !value.artifact_family && !value.artifactFamily) {
+      addFinding(findings, {
+        severity: 'warning',
+        code: 'CREATE_PATTERN_ARTIFACT_UNSPECIFIED',
+        areaId: area.id,
+        field: field(area.id, 'scope.writable_create_patterns.artifact'),
+        message: `Create pattern does not declare the artifact it creates: ${pattern}.`,
+        impact: 'Hive Lite cannot explain which required artifact this create permission covers.',
+        fix: 'Add artifact such as service_impl, controller, dto, migration, or test.',
+      });
+    }
+    if (intentKinds.length === 0) {
+      addFinding(findings, {
+        severity: 'warning',
+        code: 'CREATE_PATTERN_INTENT_KINDS_UNSPECIFIED',
+        areaId: area.id,
+        field: field(area.id, 'scope.writable_create_patterns.intent_kinds'),
+        message: `Create pattern does not declare the intent kinds it supports: ${pattern}.`,
+        impact: 'The create permission may apply to more intents than intended.',
+        fix: 'Add intent_kinds such as add_provider_proxy or add_endpoint.',
+      });
+    }
+  }
+}
+
+function validateCapabilityLedger(root, area, findings) {
+  const normalized = normalizeAreaScope(root, area);
+  const raw = rawScope(area);
+  const references = readableReferences(area);
+  const updateWritable = [
+    ...raw.direct.map((value) => ({ pattern: patternFrom(value), source: 'writable_direct' })),
+    ...normalized.writableExisting.map((item) => ({ pattern: patternFrom(item), source: 'writable_existing' })),
+  ].filter((item) => item.pattern);
+
+  for (const reference of references) {
+    const conflict = updateWritable.find((item) => matchesPattern(reference.path, item.pattern));
+    if (conflict) {
+      addFinding(findings, {
+        severity: 'warning',
+        code: 'REFERENCE_WRITABLE_SCOPE_CONFLICT',
+        areaId: area.id,
+        field: field(area.id, 'scope.readable_reference'),
+        message: `Reference-only file also matches update-capable writable scope: ${reference.path}.`,
+        impact: 'A peer example or copy source may be treated as editable for an intent where it should only guide implementation.',
+        fix: 'Keep peer examples under readable_reference only, or remove the conflict by using writable_create_patterns for new-peer files.',
+        metrics: { writableScope: conflict.pattern, writableSource: conflict.source },
+      });
+    }
+  }
+
+  const families = configuredArtifactFamilies(area);
+  for (const family of families) {
+    for (const artifact of family.createRequires) {
+      if (!normalized.writableCreatePatterns.some((item) => patternArtifactMatches(item, artifact))) {
+        addFinding(findings, {
+          severity: 'warning',
+          code: 'ARTIFACT_CREATE_PATTERN_MISSING',
+          areaId: area.id,
+          field: field(area.id, `artifact_families.${family.id}.create_requires`),
+          message: `Artifact family ${family.id} declares create artifact ${artifact}, but no writable_create_patterns entry covers it.`,
+          impact: 'Create intents for this family may stay in discovery_context until the map records narrow create permission.',
+          fix: `Add a narrow scope.writable_create_patterns entry with artifact: ${artifact}.`,
+        });
+      }
+    }
+    for (const hook of family.hooks) {
+      if (!normalized.writableExisting.some((item) => patternArtifactMatches(item, hook))) {
+        addFinding(findings, {
+          severity: 'warning',
+          code: 'ARTIFACT_HOOK_SCOPE_MISSING',
+          areaId: area.id,
+          field: field(area.id, `artifact_families.${family.id}.hooks`),
+          message: `Artifact family ${family.id} declares required hook ${hook}, but no writable_existing entry covers it.`,
+          impact: 'Create intents that also need an existing registry/router/index update may not receive a complete edit permit.',
+          fix: `Add an exact scope.writable_existing entry with artifact: ${hook}.`,
+        });
+      }
+    }
+  }
+
+  validateCreatePatternMetadata(area, findings);
+
+  const peerExamples = references.filter((item) => item.peerIdentity || item.artifact).length;
+  if (areaLooksPeerBased(area) && peerExamples > 0 && normalized.writableCreatePatterns.length === 0) {
+    addFinding(findings, {
+      severity: 'warning',
+      code: 'PEER_EXAMPLES_WITHOUT_CREATE_PATTERNS',
+      areaId: area.id,
+      field: field(area.id, 'scope.readable_reference'),
+      message: 'Peer/example files are mapped, but the area has no create capability.',
+      impact: 'New peer/provider/adapter intents can use examples for context but still lack certified create permission.',
+      fix: 'Keep peer examples under readable_reference and add narrow scope.writable_create_patterns for new peer artifacts.',
+    });
+  }
+  if (configuredPeerFileTemplateCount(area) > 0 && normalized.writableCreatePatterns.length === 0) {
+    addFinding(findings, {
+      severity: 'warning',
+      code: 'PEER_TEMPLATES_WITHOUT_CREATE_PATTERNS',
+      areaId: area.id,
+      field: field(area.id, 'peer_file_templates'),
+      message: 'peer_file_templates are configured, but the area has no create capability.',
+      impact: 'Templates can explain candidate files but cannot grant create permission.',
+      fix: 'Add narrow scope.writable_create_patterns for templates that represent allowed new files.',
+    });
+  }
+}
+
 function validateWritableScope(root, tracked, area, findings) {
   const normalized = normalizeAreaScope(root, area);
   const raw = rawScope(area);
@@ -957,6 +1164,7 @@ function evaluateMapHealth(root, options = {}) {
     validateFindTerms(area, aliasOwners, findings);
     validateEntryPoints(root, area, findings);
     validateWritableScope(root, tracked, area, findings);
+    validateCapabilityLedger(root, area, findings);
     validateValidation(area, profilesById, scripts, findings);
     validateVerification(area, profilesById, findings);
     validateRisk(area, findings);