@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

package/src/lib/ai/ai-checks.js

@@ -0,0 +1,182 @@
+/**
+ * ai-checks.js — o coletor das cinco checagens de `morph-spec doctor --ai`.
+ *
+ * Contrato de uma checagem:
+ *
+ *     { id, name, status: 'ok'|'warn'|'error'|'skip', reason?, findings: [], unverified?: [] }
+ *
+ * Duas regras que este módulo existe para tornar mecânicas:
+ *
+ * 1. **`status: 'skip'` sai com `reason` obrigatória.** "Não verificado" sem
+ *    motivo é ruído — quem lê não consegue decidir se falta insumo ou se falta
+ *    checagem. Um `skip` sem razão é bug deste arquivo, e há canário.
+ * 2. **`null` de uma função de checagem é DESCONHECIDO, nunca "não achei
+ *    nada".** `[]` é "perguntei e não achei" e vira `ok`. É a doutrina de
+ *    `pr-index.js`, já viva no `doctor`.
+ *
+ * E uma proibição: **nada alcançável daqui escreve.** Os candidatos óbvios ao
+ * erro — `scripts/generate-ai-pin-props.js` e
+ * `scripts/generate-standards-registry.js` — escrevem por padrão e NÃO entram
+ * no grafo de imports deste módulo. É a lição do T10 da #90, onde a auditoria
+ * ia ALOCAR um bloco de porta ao auditar, inventando o estado que reportava.
+ * O canário assere a lista de chamadas feitas, não só o retorno.
+ */
+
+import { scanAiPackageRefs } from './ai-project-scan.js';
+import { resolveAiPin, auditPinDrift } from './pin-drift.js';
+import { locateAiRegistry, auditModelPricing, auditApiPerAlias } from './registry-audit.js';
+import { auditRenamedApi, auditPromptSource, renamedApiGate } from './code-audit.js';
+
+/** Os cinco ids, na ordem em que o relatório os imprime. */
+export const AI_CHECK_IDS = ['pin-drift', 'removed-api', 'pricing-missing', 'api-per-alias', 'prompt-source'];
+
+/** Nome legível de cada checagem. */
+export const AI_CHECK_NAMES = {
+  'pin-drift': 'pin × projeto (versões de pacote de IA)',
+  'removed-api': 'API renomeada antes do 1.0 GA',
+  'pricing-missing': 'tarifa por alias do registry de modelos',
+  'api-per-alias': 'campo `api` por alias do registry de modelos',
+  'prompt-source': 'fonte declarada das instruções do agente',
+};
+
+/** O pacote cuja versão gateia a checagem de API renomeada. */
+export const MAF_PACKAGE = 'Microsoft.Agents.AI';
+
+/** As dependências reais. Substituíveis inteiras ou em parte, por canário. */
+export function defaultAiDeps() {
+  return {
+    scanAiPackageRefs,
+    resolveAiPin,
+    auditPinDrift,
+    renamedApiGate,
+    auditRenamedApi,
+    locateAiRegistry,
+    auditModelPricing,
+    auditApiPerAlias,
+    auditPromptSource,
+  };
+}
+
+function statusFrom(findings) {
+  if (findings.some((f) => f.severity === 'error')) return 'error';
+  if (findings.some((f) => f.severity === 'warn')) return 'warn';
+  return 'ok';
+}
+
+function skip(id, reason, extra = {}) {
+  return { id, name: AI_CHECK_NAMES[id], status: 'skip', reason, findings: [], ...extra };
+}
+
+function resolved(id, findings, extra = {}) {
+  return { id, name: AI_CHECK_NAMES[id], status: statusFrom(findings), findings, ...extra };
+}
+
+function skipAll(reason) {
+  return AI_CHECK_IDS.map((id) => skip(id, reason));
+}
+
+/**
+ * Roda as cinco checagens sobre um projeto.
+ *
+ * As três condições de silêncio total acontecem ANTES de qualquer leitura do
+ * pin — e é essa ordem, não o retorno, que o canário assere: sem `.csproj`
+ * alcançável, `resolveAiPin` não é sequer chamada.
+ *
+ * @param {string} targetPath - raiz do projeto
+ * @param {object} [options]
+ * @param {object|null} [options.config] - `.morph/config/config.json` já lido
+ * @param {object} [options.deps] - substituição parcial de `defaultAiDeps()`
+ * @returns {Array<{id: string, name: string, status: string, reason?: string, findings: Array}>}
+ */
+export function collectAiChecks(targetPath, { config = null, deps = {} } = {}) {
+  const d = { ...defaultAiDeps(), ...deps };
+
+  const scan = d.scanAiPackageRefs(targetPath);
+
+  // Condição 4 do silêncio: UNKNOWN nunca vira "sem drift".
+  if (scan === null) {
+    return skipAll('nenhum arquivo de projeto .NET foi legível a partir desta raiz — '
+      + 'não verificado, o que NÃO é o mesmo que "sem drift"');
+  }
+
+  // Condição 1: sem `.csproj` alcançável. O pin nem é lido.
+  if (scan.projectFiles.length === 0) {
+    return skipAll('nenhum `.csproj` alcançável a partir desta raiz — não há projeto .NET a julgar');
+  }
+
+  // Condição 3: `.csproj` presentes, nenhum pacote de IA entre eles.
+  const aiPackages = scan.packages.filter((p) => p.ai);
+  if (aiPackages.length === 0) {
+    return skipAll(`${scan.projectFiles.length} projeto(s) .NET varrido(s) e nenhum pacote de IA `
+      + 'declarado entre eles — um projeto .NET sem MAF não é um projeto MAF quebrado');
+  }
+
+  const unverified = scan.unreadable.slice();
+  const checks = [];
+
+  // ── pin-drift ────────────────────────────────────────────────────────────
+  // Condição 2: sem pin resolvível, a checagem que depende dele sai skip.
+  const pin = d.resolveAiPin(targetPath);
+  if (!pin) {
+    checks.push(skip('pin-drift', 'nenhum `ai-pin.json` resolvível (nem em `.morph/framework/`, nem '
+      + 'no pacote da CLI) — falta de régua é ausência de dado, nunca defeito do projeto', { unverified }));
+  } else {
+    const findings = d.auditPinDrift({ scan, pin });
+    checks.push(findings === null
+      ? skip('pin-drift', 'a comparação com o pin não pôde ser feita', { unverified })
+      : resolved('pin-drift', findings, { unverified }));
+  }
+
+  // ── removed-api ──────────────────────────────────────────────────────────
+  const maf = scan.packages.find((p) => p.name === MAF_PACKAGE) ?? null;
+  const gate = d.renamedApiGate(maf);
+  if (gate !== null) {
+    checks.push(skip('removed-api', gate));
+  } else {
+    const findings = d.auditRenamedApi(targetPath, { mafPackage: maf });
+    checks.push(findings === null
+      ? skip('removed-api', 'a varredura de `.cs` não pôde ser feita')
+      : resolved('removed-api', findings));
+  }
+
+  // ── pricing-missing e api-per-alias ──────────────────────────────────────
+  const registry = d.locateAiRegistry(targetPath, config);
+  const noRegistry = 'nenhum registry de modelos encontrado — nem `project.ai.modelRegistry` no '
+    + 'config, nem um `.json` com `defaultAlias` + mapa de aliases, nem uma seção `Pricing` num '
+    + '`appsettings*.json`';
+
+  const pricing = registry ? d.auditModelPricing(registry) : null;
+  checks.push(pricing === null ? skip('pricing-missing', noRegistry) : resolved('pricing-missing', pricing));
+
+  const perAlias = registry ? d.auditApiPerAlias(registry) : null;
+  checks.push(perAlias === null
+    ? skip('api-per-alias', registry
+      ? 'o registry encontrado não declara um mapa de aliases — não há alias sobre o qual perguntar'
+      : noRegistry)
+    : resolved('api-per-alias', perAlias));
+
+  // ── prompt-source ────────────────────────────────────────────────────────
+  const prompts = d.auditPromptSource(targetPath);
+  checks.push(prompts === null
+    ? skip('prompt-source', 'nenhum `.cs` alcançável a partir desta raiz')
+    : resolved('prompt-source', prompts));
+
+  return checks;
+}
+
+/**
+ * Código de saída do `doctor --ai`: 1 quando há ao menos um `error`, 0 caso
+ * contrário. `warn` e `skip` NUNCA mudam o código de saída — só `pin-drift`
+ * produz `error`, e só na faixa flutuante, a única classe com prejuízo medido.
+ *
+ * @param {Array<{status: string}>} checks
+ * @returns {0|1}
+ */
+export function aiExitCode(checks) {
+  return checks.some((c) => c.status === 'error') ? 1 : 0;
+}
+
+/** true quando NENHUMA checagem teve insumo — o relatório sai em uma linha. */
+export function allSkipped(checks) {
+  return checks.length > 0 && checks.every((c) => c.status === 'skip');
+}

package/src/lib/ai/ai-project-scan.js

@@ -0,0 +1,347 @@
+/**
+ * ai-project-scan.js — varredura READ-ONLY dos `.csproj` / `Directory.Packages.props`
+ * de um projeto .NET, para responder "o que este projeto declara sobre pacotes de IA?".
+ *
+ * Três invariantes deste módulo, todas cobradas por canário:
+ *
+ * 1. **Nada aqui escreve.** Nenhum import de `fs` que mute, nenhum `spawn`.
+ *    A auditoria não pode inventar o estado que reporta — é a lição do T10 da
+ *    #90, onde a auditoria de portas ia ALOCAR um bloco ao auditar.
+ * 2. **`null` é DESCONHECIDO, `[]` é "perguntei e não achei".** Colapsar os
+ *    dois é a doutrina que `src/lib/git/pr-index.js` já pinou neste repositório.
+ *    Aqui: `scanAiPackageRefs` devolve `null` quando havia arquivos candidatos
+ *    e NENHUM foi legível; devolve um resultado com `projectFiles: []` quando
+ *    varreu e não achou `.csproj` nenhum.
+ * 3. **Worktree é o checkout de OUTRA feature.** `worktrees/` e `.worktrees/`
+ *    ficam fora da varredura pela mesma razão pinada em `test-runner.js`:
+ *    varrê-los reporta sobre código fora da árvore avaliada. Os nomes vêm de
+ *    `src/lib/worktree/dirs.js`, nunca duplicados aqui.
+ */
+
+import { readdirSync, readFileSync, statSync, existsSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { WORKTREE_DIR_NAMES } from '../worktree/dirs.js';
+
+/** Diretórios que a varredura nunca desce. */
+export const SCAN_IGNORED_DIRS = new Set([
+  'node_modules',
+  'bin',
+  'obj',
+  '.git',
+  ...WORKTREE_DIR_NAMES,
+]);
+
+/**
+ * Prefixos de pacote NuGet que caracterizam "pacote de IA".
+ *
+ * Deliberadamente curto: a lista existe para decidir se há assunto (condição 3
+ * do silêncio do `doctor --ai`), não para catalogar o ecossistema. Um pacote de
+ * IA fora desta lista aparece na varredura como pacote comum e, se estiver no
+ * pin, `pin-drift` o pega mesmo assim — o pin é a outra metade do predicado.
+ */
+export const AI_PACKAGE_PREFIXES = [
+  'Microsoft.Agents.AI',
+  'Microsoft.Extensions.AI',
+  'Microsoft.SemanticKernel',
+  'OpenAI',
+  'Azure.AI.',
+  'Google.GenAI',
+  'ModelContextProtocol',
+  'Anthropic.',
+];
+
+/**
+ * @param {string} name - nome do pacote NuGet
+ * @returns {boolean} true quando o nome casa com um dos prefixos de IA
+ */
+export function isAiPackage(name) {
+  if (typeof name !== 'string' || name.length === 0) return false;
+  return AI_PACKAGE_PREFIXES.some(
+    (p) => name === p || name.startsWith(p.endsWith('.') ? p : `${p}.`)
+  );
+}
+
+/** Remove o BOM UTF-8 do início do texto (mesmo cuidado de `doctor.js` e `env.js`). */
+function stripBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+/**
+ * Checagem de boa-formação de XML suficiente para MSBuild, sem dependência nova.
+ *
+ * Não valida schema: valida que as tags fecham na ordem certa e que todo `<`
+ * tem o seu `>`. É o predicado que separa "li o arquivo" de "não pude
+ * perguntar" — e é ele que faz um `.csproj` truncado virar `unreadable` em vez
+ * de virar "sem drift".
+ *
+ * @param {string} xml
+ * @returns {boolean}
+ */
+export function isWellFormedXml(xml) {
+  const stack = [];
+  let i = 0;
+  while (i < xml.length) {
+    const lt = xml.indexOf('<', i);
+    if (lt === -1) break;
+
+    if (xml.startsWith('<!--', lt)) {
+      const end = xml.indexOf('-->', lt + 4);
+      if (end === -1) return false;
+      i = end + 3;
+      continue;
+    }
+    if (xml.startsWith('<![CDATA[', lt)) {
+      const end = xml.indexOf(']]>', lt + 9);
+      if (end === -1) return false;
+      i = end + 3;
+      continue;
+    }
+    if (xml.startsWith('<?', lt) || xml.startsWith('<!', lt)) {
+      const end = xml.indexOf('>', lt);
+      if (end === -1) return false;
+      i = end + 1;
+      continue;
+    }
+
+    const gt = xml.indexOf('>', lt);
+    if (gt === -1) return false;
+    const raw = xml.slice(lt + 1, gt).trim();
+    if (raw.length === 0) return false;
+
+    if (raw.startsWith('/')) {
+      const name = raw.slice(1).trim();
+      if (stack.pop() !== name) return false;
+    } else if (!raw.endsWith('/')) {
+      const name = raw.split(/[\s/>]/)[0];
+      if (!name) return false;
+      stack.push(name);
+    }
+    i = gt + 1;
+  }
+  return stack.length === 0;
+}
+
+/** Todas as tags de um nome, com os atributos crus. */
+function* elements(xml, tagName) {
+  const re = new RegExp(`<${tagName}\\b([^>]*?)(/?)>`, 'g');
+  let m;
+  while ((m = re.exec(xml)) !== null) {
+    yield { attrs: m[1], selfClosing: m[2] === '/', index: m.index, end: re.lastIndex };
+  }
+}
+
+/** Valor de um atributo dentro do texto cru de atributos de uma tag. */
+function attr(attrs, name) {
+  const m = new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`, 'i').exec(attrs)
+    || new RegExp(`\\b${name}\\s*=\\s*'([^']*)'`, 'i').exec(attrs);
+  return m ? m[1].trim() : null;
+}
+
+/**
+ * Elemento filho `<Version>x</Version>` de um `<PackageReference>` não
+ * auto-fechado. Recebe o XML e o índice logo após a tag de abertura.
+ */
+function childVersion(xml, startIndex, tagName) {
+  const close = xml.indexOf(`</${tagName}>`, startIndex);
+  if (close === -1) return null;
+  const inner = xml.slice(startIndex, close);
+  const m = /<Version\s*>([^<]*)<\/Version\s*>/i.exec(inner);
+  return m ? m[1].trim() : null;
+}
+
+/**
+ * Classifica a string de versão declarada no projeto.
+ *
+ * - `fixed`      — `1.20.0` ou a forma de igualdade exata `[1.20.0]`
+ * - `floating`   — contém `*`, ou é intervalo (`[1.0,)`, `[1.0,2.0)`, `(,2.0]`)
+ * - `unresolved` — referência a propriedade MSBuild (`$(MafVersion)`): a
+ *   varredura NÃO resolve propriedades, e chutar seria inventar o dado
+ * - `absent`     — sem versão declarada e sem entrada de CPM
+ *
+ * @param {string|null} raw
+ * @returns {{ kind: 'fixed'|'floating'|'unresolved'|'absent', value: string|null }}
+ */
+export function classifyVersion(raw) {
+  if (raw === null || raw === undefined || String(raw).trim() === '') {
+    return { kind: 'absent', value: null };
+  }
+  const value = String(raw).trim();
+  if (value.includes('$(')) return { kind: 'unresolved', value };
+  if (value.includes('*')) return { kind: 'floating', value };
+  if (/^\[\s*[^,\[\]()]+\s*\]$/.test(value)) {
+    return { kind: 'fixed', value: value.slice(1, -1).trim() };
+  }
+  if (/[[\](),]/.test(value)) return { kind: 'floating', value };
+  return { kind: 'fixed', value };
+}
+
+/**
+ * Coleta recursiva de arquivos que casam com um predicado, respeitando as
+ * exclusões de `SCAN_IGNORED_DIRS`.
+ *
+ * Exportada porque `registry-audit.js` e `code-audit.js` precisam da MESMA
+ * travessia com as MESMAS exclusões. Uma segunda cópia da lista de diretórios
+ * ignorados é como um dos três volta a varrer `worktrees/` sozinho.
+ *
+ * @param {string} root
+ * @param {(name: string, fullPath: string) => boolean} matches
+ * @returns {string[]}
+ */
+export function collectProjectFiles(root, matches) {
+  const out = [];
+  if (!root || !existsSync(root)) return out;
+  collectFiles(root, matches, out);
+  return out;
+}
+
+/** Coleta recursiva de arquivos que casam com um predicado, respeitando as exclusões. */
+function collectFiles(root, matches, out, depth = 0) {
+  if (depth > 24) return;
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const name = entry.name;
+    const full = join(root, name);
+    let isDir = entry.isDirectory();
+    if (entry.isSymbolicLink()) {
+      // Junction/symlink: pode apontar para fora da árvore (é assim que um
+      // worktree do Windows enxerga `.claude/`). Não descemos.
+      continue;
+    }
+    if (isDir) {
+      if (SCAN_IGNORED_DIRS.has(name)) continue;
+      collectFiles(full, matches, out, depth + 1);
+      continue;
+    }
+    if (matches(name, full)) out.push(full);
+  }
+}
+
+/**
+ * Varre `root` e devolve o que os projetos .NET declaram sobre pacotes.
+ *
+ * Sem limite de 10 arquivos (o de `scanStackDependencies`, que é do relatório
+ * de arquitetura e tem outro consumidor): uma solução .NET real tem dezenas de
+ * `.csproj`, e cortar em 10 é reportar sobre uma amostra chamando-a de todo.
+ *
+ * @param {string} root - raiz da varredura (o projeto)
+ * @returns {null | {
+ *   projectFiles: string[],
+ *   cpmFiles: string[],
+ *   unreadable: string[],
+ *   packages: Array<{ name: string, file: string, ai: boolean,
+ *                     version: string|null, versionKind: string,
+ *                     declared: string|null, fromCpm: boolean }>
+ * }} `null` = não pude perguntar (havia candidatos e nenhum era legível).
+ */
+export function scanAiPackageRefs(root) {
+  if (!root || !existsSync(root)) return null;
+  try {
+    if (!statSync(root).isDirectory()) return null;
+  } catch {
+    return null;
+  }
+
+  const projectFiles = [];
+  const cpmFiles = [];
+  collectFiles(root, (n) => n.toLowerCase().endsWith('.csproj'), projectFiles);
+  collectFiles(root, (n) => n.toLowerCase() === 'directory.packages.props', cpmFiles);
+
+  const candidates = [...cpmFiles, ...projectFiles];
+  if (candidates.length === 0) {
+    // Perguntei e não achei — NÃO é desconhecido.
+    return { projectFiles: [], cpmFiles: [], unreadable: [], packages: [] };
+  }
+
+  const unreadable = [];
+  const readable = new Map();
+  for (const file of candidates) {
+    let xml;
+    try {
+      xml = stripBom(readFileSync(file, 'utf8'));
+    } catch {
+      unreadable.push(file);
+      continue;
+    }
+    if (!isWellFormedXml(xml)) {
+      unreadable.push(file);
+      continue;
+    }
+    readable.set(file, xml);
+  }
+
+  if (readable.size === 0) {
+    // Havia o que perguntar e nenhuma resposta chegou: DESCONHECIDO.
+    return null;
+  }
+
+  // Central Package Management primeiro: um PackageReference sem Version num
+  // projeto com CPM não é achado de versão ausente (UC-24 A1).
+  const cpm = new Map();
+  for (const file of cpmFiles) {
+    const xml = readable.get(file);
+    if (!xml) continue;
+    for (const el of elements(xml, 'PackageVersion')) {
+      const name = attr(el.attrs, 'Include') ?? attr(el.attrs, 'Update');
+      if (!name) continue;
+      const version = attr(el.attrs, 'Version')
+        ?? (el.selfClosing ? null : childVersion(xml, el.end, 'PackageVersion'));
+      cpm.set(name, { version, file });
+    }
+  }
+
+  const packages = [];
+  for (const file of projectFiles) {
+    const xml = readable.get(file);
+    if (!xml) continue;
+    for (const el of elements(xml, 'PackageReference')) {
+      const name = attr(el.attrs, 'Include') ?? attr(el.attrs, 'Update');
+      if (!name) continue;
+      const inline = attr(el.attrs, 'Version')
+        ?? (el.selfClosing ? null : childVersion(xml, el.end, 'PackageReference'));
+      const central = cpm.get(name);
+      const fromCpm = inline === null && central !== undefined;
+      const declared = inline !== null ? inline : (fromCpm ? central.version : null);
+      const { kind, value } = classifyVersion(declared);
+      packages.push({
+        name,
+        file,
+        ai: isAiPackage(name),
+        version: value,
+        versionKind: kind,
+        declared,
+        fromCpm,
+      });
+    }
+  }
+
+  // Um Directory.Packages.props com PackageVersion de pacote de IA e nenhum
+  // .csproj que o referencie ainda declara a intenção — mas não é uso, e este
+  // módulo reporta declaração de uso. Fica de fora, de propósito.
+
+  return { projectFiles, cpmFiles, unreadable, packages };
+}
+
+/**
+ * Versão declarada de um pacote específico, ou `null` quando o projeto não a
+ * declara de forma resolvível. Usado pelo gate do `removed-api` (só roda com
+ * `Microsoft.Agents.AI` >= 1.0) e pelo relatório.
+ *
+ * @param {ReturnType<typeof scanAiPackageRefs>} scan
+ * @param {string} name
+ * @returns {{ name: string, version: string|null, versionKind: string, declared: string|null, file: string } | null}
+ */
+export function findPackage(scan, name) {
+  if (!scan || !Array.isArray(scan.packages)) return null;
+  return scan.packages.find((p) => p.name === name) ?? null;
+}
+
+/** Nomes de arquivo (sem diretório) dos projetos varridos — para mensagens. */
+export function projectFileNames(scan) {
+  if (!scan) return [];
+  return scan.projectFiles.map((f) => basename(f));
+}