@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

package/src/lib/ai/registry-audit.js

@@ -0,0 +1,285 @@
+/**
+ * registry-audit.js — o registry de modelos do projeto: tarifa por alias e
+ * protocolo (`api`) por alias.
+ *
+ * As duas perguntas saem do standard `ai-agents/providers/model-registry.md`,
+ * não da memória de quem implementa:
+ *
+ *   - **tarifa por alias** — um alias sem tarifa é um custo que ninguém
+ *     consegue prever antes de a chamada ser paga. O caso medido no acervo é o
+ *     GHLBrain, cujo mapa `Pricing.Models` é literalmente `{}`.
+ *   - **`api` por alias** — o standard mede, sobre o pin, que
+ *     `AgentApi.Responses = 0`, ou seja `default(AgentApi)` é Responses, e que
+ *     `ModelRegistry.ReadApi` devolve `AgentApi.Responses` quando o campo está
+ *     ausente. A ausência do campo, portanto, NÃO é defeito: é uma decisão
+ *     tomada por omissão. O achado NOMEIA o default assumido e pede
+ *     confirmação — nunca afirma defeito.
+ *
+ * Severidade: `warn` nas duas. Só `pin-drift` produz `error`.
+ */
+
+import { readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { isAbsolute, join, basename } from 'node:path';
+import { collectProjectFiles } from './ai-project-scan.js';
+import { jsoncToJson } from './comment-stripper.js';
+
+/** Limite de tamanho para um JSON candidato (bytes de texto) — evita ler dumps. */
+const MAX_JSON_CHARS = 512 * 1024;
+
+/**
+ * Lê um candidato a registry aceitando **JSONC**.
+ *
+ * Não é indulgência: é paridade com o leitor de produção. O exemplar canônico
+ * `framework/templates/dotnet/ai-kit/src/Morph.AiKit/Providers/model-registry.v2.json`
+ * — que diz na primeira linha "copie para `config/model-registry.json` no
+ * projeto" — tem 20 linhas de `//`, e `ModelRegistry.FromJson` do kit declara
+ * `CommentHandling = JsonCommentHandling.Skip` + `AllowTrailingCommas = true`.
+ * Com `JSON.parse` cru, as duas checagens de registry saíam `skip` sobre a
+ * ÚNICA forma que existem para auditar — e `skip` não muda o código de saída,
+ * então o silêncio era total. A auditoria tem de enxergar a mesma forma que o
+ * leitor de produção enxerga.
+ */
+function readJsonSafe(file) {
+  try {
+    const raw = readFileSync(file, 'utf8');
+    if (raw.length > MAX_JSON_CHARS) return null;
+    const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return JSON.parse(jsoncToJson(text));
+    }
+  } catch {
+    return null;
+  }
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** A forma que `ai-agents/providers/model-registry.md` define. */
+function asAliasSource(file, data) {
+  if (!isPlainObject(data)) return null;
+  if (typeof data.defaultAlias !== 'string') return null;
+  if (!isPlainObject(data.aliases)) return null;
+  return { file, aliases: data.aliases, defaultAlias: data.defaultAlias, data };
+}
+
+/** A forma medida no GHLBrain: a seção `Pricing` de um `appsettings*.json`. */
+function asPricingSource(file, data) {
+  if (!isPlainObject(data)) return null;
+  const pricing = data.Pricing ?? data.pricing;
+  if (!isPlainObject(pricing)) return null;
+  const models = pricing.Models ?? pricing.models;
+  if (!isPlainObject(models)) return null;
+  return { file, models };
+}
+
+/**
+ * Localiza o registry de modelos do projeto.
+ *
+ * Ordem, primeira ocorrência ganha (spec §3.5):
+ *   1. path declarado em `.morph/config/config.json → project.ai.modelRegistry`;
+ *   2. um `*.json` cujo objeto raiz tenha `defaultAlias` **e** um mapa `aliases`;
+ *   3. a seção `Pricing` de um `appsettings*.json`.
+ *
+ * @param {string} root - raiz do projeto
+ * @param {object|null} config - conteúdo de `.morph/config/config.json`, se houver
+ * @returns {null | { aliasSource: object|null, pricingSource: object|null }}
+ *   `null` quando NENHUMA das três formas foi encontrada.
+ */
+export function locateAiRegistry(root, config = null) {
+  let aliasSource = null;
+  let pricingSource = null;
+
+  const declared = config?.project?.ai?.modelRegistry;
+  if (typeof declared === 'string' && declared.trim()) {
+    const file = isAbsolute(declared) ? declared : join(root, declared);
+    if (existsSync(file)) {
+      const data = readJsonSafe(file);
+      aliasSource = asAliasSource(file, data);
+      pricingSource = extractPricingFromRegistry(file, data) ?? pricingSource;
+    }
+  }
+
+  if (!aliasSource) {
+    const candidates = collectProjectFiles(root, (name) => name.toLowerCase().endsWith('.json'));
+    for (const file of candidates) {
+      const data = readJsonSafe(file);
+      const found = asAliasSource(file, data);
+      if (found) {
+        aliasSource = found;
+        pricingSource = pricingSource ?? extractPricingFromRegistry(file, data);
+        break;
+      }
+    }
+  }
+
+  if (!pricingSource) {
+    const appsettings = collectProjectFiles(root, (name) => {
+      const lower = name.toLowerCase();
+      return lower.startsWith('appsettings') && lower.endsWith('.json');
+    });
+    for (const file of appsettings) {
+      const found = asPricingSource(file, readJsonSafe(file));
+      if (found) { pricingSource = found; break; }
+    }
+  }
+
+  if (!aliasSource && !pricingSource) return null;
+  return { aliasSource, pricingSource };
+}
+
+/** Mapa de tarifas embutido no próprio registry de modelos, quando existir. */
+function extractPricingFromRegistry(file, data) {
+  if (!isPlainObject(data)) return null;
+  const pricing = data.pricing ?? data.Pricing;
+  if (isPlainObject(pricing)) {
+    const models = pricing.Models ?? pricing.models;
+    return { file, models: isPlainObject(models) ? models : pricing };
+  }
+  return null;
+}
+
+/** O alias declara tarifa **no próprio elemento** (a forma v2 do exemplar canônico)? */
+function aliasHasPricing(def) {
+  return isPlainObject(def) && isPlainObject(def.pricing);
+}
+
+/** O alias declara a AUSÊNCIA de tarifa por escrito? */
+function aliasHasWaiver(def) {
+  return isPlainObject(def) && typeof def.pricingWaiver === 'string' && def.pricingWaiver.trim() !== '';
+}
+
+/**
+ * O documento usa a forma **por alias** (`pricing` / `pricingWaiver` dentro de
+ * cada alias) em vez da forma de mapa no topo?
+ *
+ * Basta UM alias declarar qualquer uma das duas: um documento meio-preenchido
+ * ainda é um documento na forma v2, e os aliases que faltam é que são o achado.
+ */
+export function usesPerAliasPricing(aliasSource) {
+  if (!aliasSource) return false;
+  return Object.values(aliasSource.aliases).some((d) => aliasHasPricing(d) || aliasHasWaiver(d));
+}
+
+/**
+ * Todo alias do registry tem uma DECISÃO de tarifa?
+ *
+ * Duas formas, e a checagem cobra a que o documento usa:
+ *
+ * 1. **Por alias** (`model-registry.v2.json`, o exemplar que o framework manda
+ *    copiar) — a REGRA DURA escrita no próprio exemplar e imposta por
+ *    `ModelRegistry.ReadPricing`: *"todo alias declara `pricing` OU
+ *    `pricingWaiver` — nunca os dois, nunca nenhum"*. Um `pricingWaiver` é uma
+ *    tarifa **decidida**: a ausência está escrita, não esquecida, e acusá-la
+ *    seria gritar em código correto.
+ * 2. **Mapa no topo** (`pricing` na raiz, ou a seção `Pricing.Models` de um
+ *    `appsettings*.json` — a forma medida no GHLBrain, cujo mapa é
+ *    literalmente `{}`).
+ *
+ * Os achados de MAPA (`pricing-map-missing` / `pricing-map-empty`) só existem
+ * na forma 2: num documento v2 não há mapa a faltar, e emitir o achado ali era
+ * o primeiro dos seis falsos positivos sobre o exemplar canônico.
+ *
+ * @param {ReturnType<typeof locateAiRegistry>} registry
+ * @returns {null | Array<{ id: string, severity: 'warn', alias?: string, message: string }>}
+ */
+export function auditModelPricing(registry) {
+  if (!registry) return null;
+  const { aliasSource, pricingSource } = registry;
+  const findings = [];
+
+  const models = pricingSource?.models ?? null;
+  const tariffKeys = models ? new Set(Object.keys(models)) : new Set();
+  const perAlias = usesPerAliasPricing(aliasSource);
+
+  if (!perAlias) {
+    if (models === null) {
+      findings.push({
+        id: 'pricing-map-missing',
+        severity: 'warn',
+        message: 'Nenhuma tarifa encontrada: nem `pricing`/`pricingWaiver` por alias (a forma do '
+          + 'exemplar `model-registry.v2.json`), nem `pricing` na raiz, nem `Pricing.Models` num '
+          + 'appsettings. Sem tarifa não há previsão de custo antes de a chamada ser paga.',
+      });
+    } else if (tariffKeys.size === 0) {
+      findings.push({
+        id: 'pricing-map-empty',
+        severity: 'warn',
+        message: `O mapa de tarifas em \`${basename(pricingSource.file)}\` está vazio — declarado e `
+          + 'sem uma única entrada. É a forma mais silenciosa de não ter tarifa: o campo existe, o '
+          + 'dado não.',
+      });
+    }
+  }
+
+  if (aliasSource) {
+    for (const [alias, def] of Object.entries(aliasSource.aliases)) {
+      const model = isPlainObject(def) ? def.model : null;
+      const rotulo = `\`${alias}\`${model ? ` (modelo \`${model}\`)` : ''}`;
+      const hasPricing = aliasHasPricing(def);
+      const hasWaiver = aliasHasWaiver(def);
+
+      if (hasPricing && hasWaiver) {
+        findings.push({
+          id: 'alias-pricing-and-waiver',
+          severity: 'warn',
+          alias,
+          message: `O alias ${rotulo} declara \`pricing\` E \`pricingWaiver\`. A regra do exemplar `
+            + 'é uma OU a outra, nunca as duas: com as duas presentes não dá para saber se a '
+            + 'tarifa vale ou se a isenção vale.',
+        });
+        continue;
+      }
+      if (hasPricing || hasWaiver) continue; // decisão tomada — inclusive a de não haver tarifa
+
+      const cobertoPeloMapa = tariffKeys.has(alias) || (model !== null && tariffKeys.has(model));
+      if (cobertoPeloMapa) continue;
+
+      findings.push({
+        id: 'alias-without-pricing',
+        severity: 'warn',
+        alias,
+        message: `O alias ${rotulo} não declara \`pricing\` nem \`pricingWaiver\`, e não aparece em `
+          + 'nenhum mapa de tarifas. Não é a tarifa que falta: falta a DECISÃO — um `pricingWaiver` '
+          + 'com o motivo por extenso também fecha a questão.',
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Todo alias declara `api`?
+ *
+ * O default do standard é **`responses`**: medido sobre o pin, `AgentApi.Responses = 0`
+ * e `ModelRegistry.ReadApi` devolve Responses quando o campo está ausente. A mensagem
+ * nomeia esse default e PEDE CONFIRMAÇÃO — a ausência do campo é uma decisão por
+ * omissão, não um defeito. É a pergunta que o `ModelRegistry.cs` do ProspectPRO
+ * documenta ter custado um bug.
+ *
+ * @param {ReturnType<typeof locateAiRegistry>} registry
+ * @returns {null | Array<{ id: string, severity: 'warn', alias: string, message: string }>}
+ *   `null` quando não há aliases para perguntar.
+ */
+export function auditApiPerAlias(registry) {
+  if (!registry || !registry.aliasSource) return null;
+  const findings = [];
+  for (const [alias, def] of Object.entries(registry.aliasSource.aliases)) {
+    const api = isPlainObject(def) ? def.api : undefined;
+    if (typeof api === 'string' && api.trim()) continue;
+    findings.push({
+      id: 'alias-without-api',
+      severity: 'warn',
+      alias,
+      message: `O alias \`${alias}\` não declara o campo \`api\`. O registry trata a omissão como `
+        + '`responses` (Responses API) — confirme que este alias não precisa falar `chat` '
+        + '(Chat Completions). Não é acusação: é a decisão que está sendo tomada por omissão.',
+    });
+  }
+  return findings;
+}

package/src/lib/detectors/design-system-detector.js

@@ -1,188 +1,188 @@
-/**
- * @fileoverview Design System Detector
- *
- * Detects if a design system exists for the project or feature.
- * Checks multiple locations in priority order.
- *
- * @module design-system-detector
- */
-
-import { existsSync, readFileSync, readdirSync } from 'fs';
-import { join } from 'path';
-
-const SKIP_DIRS = new Set(['node_modules', '.git', '.morph', 'dist', 'build', '.next', 'obj', 'bin', '.vs']);
-const CSS_SCAN_MAX_DEPTH = 6;
-
-/**
- * Recursively walk a directory collecting files with given extensions.
- * @param {string} dir - Directory to walk
- * @param {string[]} extensions - File extensions to collect (e.g. ['.css', '.scss'])
- * @param {string[]} files - Accumulator array (mutated in-place)
- * @param {number} depth - Current recursion depth
- * @param {number} maxDepth - Maximum recursion depth
- */
-function walkDirForCss(dir, extensions, files, depth, maxDepth) {
-  if (depth > maxDepth) return;
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    if (entry.isDirectory()) {
-      if (!SKIP_DIRS.has(entry.name)) {
-        walkDirForCss(join(dir, entry.name), extensions, files, depth + 1, maxDepth);
-      }
-    } else if (entry.isFile()) {
-      const lower = entry.name.toLowerCase();
-      if (extensions.some(ext => lower.endsWith(ext))) {
-        files.push(join(dir, entry.name));
-      }
-    }
-  }
-}
-
-/**
- * Detect design system for project or feature
- * @param {string} projectPath - Root path of the project
- * @param {string|null} featureName - Feature name (optional, checks feature-level if provided)
- * @returns {Object} { hasDesignSystem, path, isProjectLevel, isFeatureLevel, source }
- */
-export function detectDesignSystem(projectPath, featureName = null) {
-  const result = {
-    hasDesignSystem: false,
-    path: null,
-    isProjectLevel: false,
-    isFeatureLevel: false,
-    source: null
-  };
-
-  // Priority 1: Feature-level design system (if feature specified)
-  if (featureName) {
-    const featureDesignSystemPath = join(
-      projectPath,
-      '.morph/features',
-      featureName,
-      '1-design',
-      'design-system.md'
-    );
-
-    if (existsSync(featureDesignSystemPath)) {
-      return {
-        hasDesignSystem: true,
-        path: featureDesignSystemPath,
-        isProjectLevel: false,
-        isFeatureLevel: true,
-        source: 'feature-output'
-      };
-    }
-  }
-
-  // Priority 2: Project-level design system (markdown)
-  const projectDesignSystemPath = join(projectPath, '.morph/context/design-system.md');
-  if (existsSync(projectDesignSystemPath)) {
-    return {
-      hasDesignSystem: true,
-      path: projectDesignSystemPath,
-      isProjectLevel: true,
-      isFeatureLevel: false,
-      source: 'project-markdown'
-    };
-  }
-
-  // Priority 3: Generated CSS design system
-  const cssDesignSystemPath = join(projectPath, 'wwwroot/css/design-system.css');
-  if (existsSync(cssDesignSystemPath)) {
-    return {
-      hasDesignSystem: true,
-      path: cssDesignSystemPath,
-      isProjectLevel: true,
-      isFeatureLevel: false,
-      source: 'generated-css'
-    };
-  }
-
-  // Priority 4: Recursively scan frontend root directories for CSS/SCSS with design tokens
-  const frontendRoots = ['wwwroot', 'styles', 'src/styles', 'src', 'public'];
-  const extensions = ['.css', '.scss'];
-  const collected = [];
-
-  for (const root of frontendRoots) {
-    const rootPath = join(projectPath, root);
-    if (existsSync(rootPath)) {
-      walkDirForCss(rootPath, extensions, collected, 0, CSS_SCAN_MAX_DEPTH);
-    }
-  }
-
-  // Deduplicate by resolved path
-  const seen = new Set();
-  const cssFiles = [];
-  for (const file of collected) {
-    if (!seen.has(file)) {
-      seen.add(file);
-      cssFiles.push(file);
-    }
-  }
-
-  // Sort for deterministic first-match across platforms
-  cssFiles.sort();
-
-  for (const cssFile of cssFiles) {
-    try {
-      const content = readFileSync(cssFile, 'utf8');
-      const hasDesignTokens = /:root\s*\{[\s\S]*?--/.test(content);
-      if (hasDesignTokens) {
-        return {
-          hasDesignSystem: true,
-          path: cssFile,
-          isProjectLevel: true,
-          isFeatureLevel: false,
-          source: 'existing-css-variables'
-        };
-      }
-    } catch {
-      // Continue checking other files
-    }
-  }
-
-  // No design system found
-  return result;
-}
-
-/**
- * Get recommended design system locations based on project type
- * @param {string} projectPath - Root path of the project
- * @returns {Object} { markdown, css, description }
- */
-export function getRecommendedLocations(projectPath) {
-  try {
-    const configPath = join(projectPath, '.morph/config/config.json');
-
-    let projectType = 'unknown';
-    if (existsSync(configPath)) {
-      const config = JSON.parse(readFileSync(configPath, 'utf8'));
-      projectType = config.project?.type || 'unknown';
-    }
-
-    // Default locations
-    const locations = {
-      markdown: '.morph/context/design-system.md',
-      css: 'public/design-system.css',
-      description: 'Project-level design system (shared across features)'
-    };
-
-    // Adjust based on project type
-    if (projectType === 'nextjs' || projectType.includes('nextjs')) {
-      locations.css = 'styles/design-system.css';
-    }
-
-    return locations;
-  } catch {
-    return {
-      markdown: '.morph/context/design-system.md',
-      css: 'wwwroot/css/design-system.css',
-      description: 'Project-level design system (shared across features)'
-    };
-  }
-}
+/**
+ * @fileoverview Design System Detector
+ *
+ * Detects if a design system exists for the project or feature.
+ * Checks multiple locations in priority order.
+ *
+ * @module design-system-detector
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '.morph', 'dist', 'build', '.next', 'obj', 'bin', '.vs']);
+const CSS_SCAN_MAX_DEPTH = 6;
+
+/**
+ * Recursively walk a directory collecting files with given extensions.
+ * @param {string} dir - Directory to walk
+ * @param {string[]} extensions - File extensions to collect (e.g. ['.css', '.scss'])
+ * @param {string[]} files - Accumulator array (mutated in-place)
+ * @param {number} depth - Current recursion depth
+ * @param {number} maxDepth - Maximum recursion depth
+ */
+function walkDirForCss(dir, extensions, files, depth, maxDepth) {
+  if (depth > maxDepth) return;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name)) {
+        walkDirForCss(join(dir, entry.name), extensions, files, depth + 1, maxDepth);
+      }
+    } else if (entry.isFile()) {
+      const lower = entry.name.toLowerCase();
+      if (extensions.some(ext => lower.endsWith(ext))) {
+        files.push(join(dir, entry.name));
+      }
+    }
+  }
+}
+
+/**
+ * Detect design system for project or feature
+ * @param {string} projectPath - Root path of the project
+ * @param {string|null} featureName - Feature name (optional, checks feature-level if provided)
+ * @returns {Object} { hasDesignSystem, path, isProjectLevel, isFeatureLevel, source }
+ */
+export function detectDesignSystem(projectPath, featureName = null) {
+  const result = {
+    hasDesignSystem: false,
+    path: null,
+    isProjectLevel: false,
+    isFeatureLevel: false,
+    source: null
+  };
+
+  // Priority 1: Feature-level design system (if feature specified)
+  if (featureName) {
+    const featureDesignSystemPath = join(
+      projectPath,
+      '.morph/features',
+      featureName,
+      '1-design',
+      'design-system.md'
+    );
+
+    if (existsSync(featureDesignSystemPath)) {
+      return {
+        hasDesignSystem: true,
+        path: featureDesignSystemPath,
+        isProjectLevel: false,
+        isFeatureLevel: true,
+        source: 'feature-output'
+      };
+    }
+  }
+
+  // Priority 2: Project-level design system (markdown)
+  const projectDesignSystemPath = join(projectPath, '.morph/context/design-system.md');
+  if (existsSync(projectDesignSystemPath)) {
+    return {
+      hasDesignSystem: true,
+      path: projectDesignSystemPath,
+      isProjectLevel: true,
+      isFeatureLevel: false,
+      source: 'project-markdown'
+    };
+  }
+
+  // Priority 3: Generated CSS design system
+  const cssDesignSystemPath = join(projectPath, 'wwwroot/css/design-system.css');
+  if (existsSync(cssDesignSystemPath)) {
+    return {
+      hasDesignSystem: true,
+      path: cssDesignSystemPath,
+      isProjectLevel: true,
+      isFeatureLevel: false,
+      source: 'generated-css'
+    };
+  }
+
+  // Priority 4: Recursively scan frontend root directories for CSS/SCSS with design tokens
+  const frontendRoots = ['wwwroot', 'styles', 'src/styles', 'src', 'public'];
+  const extensions = ['.css', '.scss'];
+  const collected = [];
+
+  for (const root of frontendRoots) {
+    const rootPath = join(projectPath, root);
+    if (existsSync(rootPath)) {
+      walkDirForCss(rootPath, extensions, collected, 0, CSS_SCAN_MAX_DEPTH);
+    }
+  }
+
+  // Deduplicate by resolved path
+  const seen = new Set();
+  const cssFiles = [];
+  for (const file of collected) {
+    if (!seen.has(file)) {
+      seen.add(file);
+      cssFiles.push(file);
+    }
+  }
+
+  // Sort for deterministic first-match across platforms
+  cssFiles.sort();
+
+  for (const cssFile of cssFiles) {
+    try {
+      const content = readFileSync(cssFile, 'utf8');
+      const hasDesignTokens = /:root\s*\{[\s\S]*?--/.test(content);
+      if (hasDesignTokens) {
+        return {
+          hasDesignSystem: true,
+          path: cssFile,
+          isProjectLevel: true,
+          isFeatureLevel: false,
+          source: 'existing-css-variables'
+        };
+      }
+    } catch {
+      // Continue checking other files
+    }
+  }
+
+  // No design system found
+  return result;
+}
+
+/**
+ * Get recommended design system locations based on project type
+ * @param {string} projectPath - Root path of the project
+ * @returns {Object} { markdown, css, description }
+ */
+export function getRecommendedLocations(projectPath) {
+  try {
+    const configPath = join(projectPath, '.morph/config/config.json');
+
+    let projectType = 'unknown';
+    if (existsSync(configPath)) {
+      const config = JSON.parse(readFileSync(configPath, 'utf8'));
+      projectType = config.project?.type || 'unknown';
+    }
+
+    // Default locations
+    const locations = {
+      markdown: '.morph/context/design-system.md',
+      css: 'public/design-system.css',
+      description: 'Project-level design system (shared across features)'
+    };
+
+    // Adjust based on project type
+    if (projectType === 'nextjs' || projectType.includes('nextjs')) {
+      locations.css = 'styles/design-system.css';
+    }
+
+    return locations;
+  } catch {
+    return {
+      markdown: '.morph/context/design-system.md',
+      css: 'wwwroot/css/design-system.css',
+      description: 'Project-level design system (shared across features)'
+    };
+  }
+}