@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

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

@@ -0,0 +1,181 @@
+/**
+ * code-audit.js — duas varreduras sobre os `.cs` do projeto.
+ *
+ *   (a) `removed-api`  — nomes renomeados ANTES do 1.0 GA do `Microsoft.Agents.AI`
+ *   (b) `prompt-source` — `Instructions` recebendo literal de string no ponto de
+ *                         construção do agente
+ *
+ * Nenhuma das duas é grep cego, e as duas são `warn`:
+ *
+ * - A #93 apurou, e o standard `ai-agents/agent-session.md` registra, que
+ *   `AgentThread` → `AgentSession` e `GetNewThread()` → `CreateSessionAsync()`
+ *   aconteceram no ciclo PRÉ-GA. Dentro do `Microsoft.Agents.AI` >= 1.0 os
+ *   nomes antigos são nomes mortos — mas o MESMO identificador pertence a
+ *   outros SDKs de agente na mesma solução, e é por isso que o achado é aviso
+ *   e a mensagem manda CONFERIR a qual cliente a chamada pertence, em vez de
+ *   afirmar defeito. Sem o pacote declarado em >= 1.0 a checagem nem roda.
+ *
+ * - O `prompt-source` é deliberadamente conservador: acusa só o literal no
+ *   ponto de construção. Leitura de arquivo, banco, configuração ou constante
+ *   nomeada não é acusada. Falso negativo é aceitável; falso positivo não —
+ *   uma checagem que grita em código correto é desligada pelo usuário na
+ *   primeira semana.
+ */
+
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { collectProjectFiles } from './ai-project-scan.js';
+import { stripComments } from './comment-stripper.js';
+
+/** Símbolos renomeados antes do 1.0 GA, e o nome vivo de cada um. */
+export const RENAMED_SYMBOLS = {
+  AgentThread: 'AgentSession',
+  GetNewThread: 'CreateSessionAsync()',
+  ChatMessageStore: 'a conversa persistida do projeto (ver ai-agents/agent-session.md)',
+};
+
+function lineOf(text, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < text.length; i++) if (text[i] === '\n') line += 1;
+  return line;
+}
+
+/** Todos os `.cs` do projeto, com as mesmas exclusões da varredura de `.csproj`. */
+export function collectCsharpFiles(root) {
+  return collectProjectFiles(root, (name) => name.toLowerCase().endsWith('.cs'));
+}
+
+/**
+ * Menor major que a versão declarada pode assumir, ou `null` quando a
+ * declaração não permite decidir.
+ *
+ * `1.0.*` e `[1.0,)` têm limite inferior 1 — sobem, nunca descem. `$(Prop)` e
+ * versão ausente NÃO permitem decidir, e decidir mesmo assim seria inventar o
+ * dado que a checagem reporta.
+ *
+ * @param {{ declared: string|null, versionKind: string }|null} pkg
+ * @returns {number|null}
+ */
+export function lowerBoundMajor(pkg) {
+  if (!pkg) return null;
+  if (pkg.versionKind === 'unresolved' || pkg.versionKind === 'absent') return null;
+  const raw = String(pkg.declared ?? '').trim();
+  // Intervalo de limite inferior aberto (`(,2.0]`): nada garante >= 1.0.
+  if (/^[[(]\s*,/.test(raw)) return 0;
+  const m = /(\d+)/.exec(raw);
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * Por que o `removed-api` NÃO roda, quando não roda.
+ *
+ * @param {{ declared: string|null, versionKind: string }|null} mafPackage
+ * @returns {string|null} razão do "não verificado", ou `null` quando pode rodar
+ */
+export function renamedApiGate(mafPackage) {
+  if (!mafPackage) {
+    return 'o projeto não declara `Microsoft.Agents.AI` — os nomes antigos não pertencem a este código';
+  }
+  const major = lowerBoundMajor(mafPackage);
+  if (major === null) {
+    return `a versão declarada de \`Microsoft.Agents.AI\` (\`${mafPackage.declared ?? 'ausente'}\`) `
+      + 'não permite decidir se é >= 1.0';
+  }
+  if (major < 1) {
+    return `\`Microsoft.Agents.AI\` está declarado em ${mafPackage.declared} (< 1.0), onde os nomes `
+      + 'antigos ainda são a API viva';
+  }
+  return null;
+}
+
+/**
+ * (a) Uso de API renomeada antes do 1.0 GA.
+ *
+ * @param {string} root
+ * @param {{ mafPackage?: object|null }} [options]
+ * @returns {null | Array<{ id: string, severity: 'warn', symbol: string, file: string, line: number, message: string }>}
+ *   `null` = não pude perguntar (gate fechado ou raiz ilegível).
+ */
+export function auditRenamedApi(root, { mafPackage = null } = {}) {
+  if (renamedApiGate(mafPackage) !== null) return null;
+
+  const files = collectCsharpFiles(root);
+  const findings = [];
+  for (const file of files) {
+    let text;
+    try {
+      text = readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    const clean = stripComments(text, { blankStrings: true });
+    for (const [dead, alive] of Object.entries(RENAMED_SYMBOLS)) {
+      const re = new RegExp(`\\b${dead}\\b`, 'g');
+      let m;
+      while ((m = re.exec(clean)) !== null) {
+        findings.push({
+          id: 'renamed-api',
+          severity: 'warn',
+          symbol: dead,
+          file: relative(root, file) || file,
+          line: lineOf(clean, m.index),
+          message: `\`${dead}\` em ${relative(root, file) || file}:${lineOf(clean, m.index)} — em `
+            + `\`Microsoft.Agents.AI\` >= 1.0 o nome vivo é \`${alive}\`; o renome aconteceu ainda `
+            + 'no ciclo pré-GA. Aviso, não erro: o mesmo identificador é legítimo em outros SDKs '
+            + 'de agente (por exemplo o `PersistentAgentsClient` do Azure AI Agents), então '
+            + 'confirme a qual cliente esta chamada pertence antes de trocar.',
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * `Instructions` recebendo literal de string no ponto de construção.
+ *
+ * Casa `Instructions = "…"`, `Instructions = @"…"`, `Instructions = $"…"`,
+ * `Instructions = """…"""` e o argumento nomeado `instructions: "…"`.
+ * NÃO casa atribuição de variável, chamada, `await`, constante nomeada nem
+ * literal dentro de comentário.
+ */
+const INSTRUCTIONS_LITERAL_RE = /(?<![\w."])(?:Instructions\s*=(?!=)|instructions\s*:)\s*(?:[$@]){0,2}"/g;
+
+/**
+ * (b) Prompt sem fonte declarada.
+ *
+ * @param {string} root
+ * @returns {null | Array<{ id: string, severity: 'warn', file: string, line: number, message: string }>}
+ */
+export function auditPromptSource(root) {
+  const files = collectCsharpFiles(root);
+  if (files.length === 0) return null;
+
+  const findings = [];
+  for (const file of files) {
+    let text;
+    try {
+      text = readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    const clean = stripComments(text);
+    INSTRUCTIONS_LITERAL_RE.lastIndex = 0;
+    let m;
+    while ((m = INSTRUCTIONS_LITERAL_RE.exec(clean)) !== null) {
+      const line = lineOf(clean, m.index);
+      const rel = relative(root, file) || file;
+      findings.push({
+        id: 'prompt-source',
+        severity: 'warn',
+        file: rel,
+        line,
+        message: `${rel}:${line} — as instruções do agente vêm de um literal de string no ponto de `
+          + 'construção. Sem fonte declarada (arquivo, banco ou configuração versionada) não há '
+          + 'como provar qual versão do prompt rodou. Ver o standard de fonte de prompt em '
+          + '`ai-agents/`.',
+      });
+    }
+  }
+  return findings;
+}

package/src/lib/ai/comment-stripper.js

@@ -0,0 +1,184 @@
+/**
+ * comment-stripper.js — apagar comentários SEM apagar o que está dentro de uma
+ * string, preservando comprimento e quebras de linha.
+ *
+ * Existe uma vez só, e serve a dois consumidores que fariam a MESMA coisa de
+ * jeitos ligeiramente diferentes se cada um escrevesse o seu:
+ *
+ *   - `code-audit.js` — não pode acusar `AgentThread` que só aparece num
+ *     comentário ou numa mensagem de log;
+ *   - `registry-audit.js` — precisa ler **JSONC**, a forma que o exemplar
+ *     canônico `model-registry.v2.json` usa e que o leitor C# do kit aceita de
+ *     propósito (`JsonCommentHandling.Skip`, `AllowTrailingCommas`).
+ *
+ * **Por que não um regex.** O exemplar tem `"http://localhost:11434/v1"` e uma
+ * `provenance` com URL. Um `replace(/\/\/.*$/gm, '')` decapitaria as duas —
+ * apagando dado e chamando isso de comentário. Um varredor que atravessa as
+ * strings primeiro é a única forma correta, e é o que está aqui.
+ *
+ * O comprimento é preservado (os removidos viram espaço, `\n` e `\r` ficam) para
+ * que índices e números de linha do texto original continuem válidos no texto
+ * limpo. É o que permite `code-audit.js` reportar `arquivo.cs:34` sem um segundo
+ * mapeamento.
+ */
+
+/**
+ * @param {string} text
+ * @param {object} [options]
+ * @param {boolean} [options.blankStrings=false]
+ *   Apaga também o CONTEÚDO das strings. **As aspas delimitadoras ficam.**
+ *
+ *   Apagá-las junto era um defeito com consequência: um elemento-string virava
+ *   espaço puro, e o detector de vírgula sobrando de `jsoncToJson` passava a
+ *   enxergar `[  ,  ,  ]` — separadores REAIS entre delimitadores que sumiram —
+ *   e apagava uma vírgula que era sintaxe. Medido: `{"tags":["a","b"]}` saía
+ *   `{"tags":["a","b" ]}`, JSON inválido, e o registry voltava a ser
+ *   `○ não verificado`. O B1 reintroduzido pela correção do B1.
+ * @param {{ unterminated?: string|null }} [options.report]
+ *   Se um objeto for passado, recebe `unterminated` = `'block-comment'`,
+ *   `'string'`, `'verbatim-string'`, `'raw-string'` ou `null`. É o canal de
+ *   diagnóstico que `jsoncToJson` usa para ficar tão estrito quanto o leitor
+ *   de produção, sem que este lexer precise lançar (ele também varre `.cs`,
+ *   onde um comentário aberto é problema do arquivo, não da varredura).
+ * @returns {string} texto do MESMO comprimento
+ */
+export function stripComments(text, { blankStrings = false, report = null } = {}) {
+  const out = text.split('');
+  const blank = (from, to) => {
+    for (let k = from; k < to && k < out.length; k++) {
+      if (out[k] !== '\n' && out[k] !== '\r') out[k] = ' ';
+    }
+  };
+  const flag = (kind) => { if (report && !report.unterminated) report.unterminated = kind; };
+  if (report) report.unterminated = null;
+
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    const next = text[i + 1];
+
+    if (c === '/' && next === '/') {
+      let end = text.indexOf('\n', i);
+      if (end === -1) end = text.length;
+      blank(i, end);
+      i = end;
+      continue;
+    }
+    if (c === '/' && next === '*') {
+      const close = text.indexOf('*/', i + 2);
+      if (close === -1) flag('block-comment');
+      const end = close === -1 ? text.length : close + 2;
+      blank(i, end);
+      i = end;
+      continue;
+    }
+
+    // Raw string literal do C#: """ ... """ — delimitadores de 3 aspas.
+    if (c === '"' && next === '"' && text[i + 2] === '"') {
+      const end = text.indexOf('"""', i + 3);
+      if (end === -1) flag('raw-string');
+      const stop = end === -1 ? text.length : end + 3;
+      if (blankStrings) blank(i + 3, end === -1 ? stop : stop - 3);
+      i = stop;
+      continue;
+    }
+
+    // Verbatim string do C#: @"..." — aspas duplicadas escapam
+    if (c === '@' && next === '"') {
+      let j = i + 2;
+      let closed = false;
+      while (j < text.length) {
+        if (text[j] === '"') {
+          if (text[j + 1] === '"') { j += 2; continue; }
+          j += 1;
+          closed = true;
+          break;
+        }
+        j += 1;
+      }
+      if (!closed) flag('verbatim-string');
+      if (blankStrings) blank(i + 2, closed ? j - 1 : j);
+      i = j;
+      continue;
+    }
+
+    if (c === '"') {
+      let j = i + 1;
+      let closed = false;
+      while (j < text.length) {
+        if (text[j] === '\\') { j += 2; continue; }
+        if (text[j] === '"') { j += 1; closed = true; break; }
+        if (text[j] === '\n') break;
+        j += 1;
+      }
+      if (!closed) flag('string');
+      if (blankStrings) blank(i + 1, closed ? j - 1 : j);
+      i = j;
+      continue;
+    }
+
+    if (c === "'") {
+      let j = i + 1;
+      let closed = false;
+      while (j < text.length) {
+        if (text[j] === '\\') { j += 2; continue; }
+        if (text[j] === "'") { j += 1; closed = true; break; }
+        if (text[j] === '\n') break;
+        j += 1;
+      }
+      if (blankStrings) blank(i + 1, closed ? j - 1 : j);
+      i = j;
+      continue;
+    }
+
+    i += 1;
+  }
+
+  return out.join('');
+}
+
+/**
+ * Converte JSONC em JSON: apaga comentários e vírgulas sobrando antes de `}`/`]`.
+ *
+ * As duas tolerâncias são **exatamente** as que `ModelRegistry.FromJson` do
+ * ai-kit declara (`CommentHandling = Skip`, `AllowTrailingCommas = true`). A
+ * ferramenta que audita o registry tem de enxergar a mesma forma que o leitor
+ * de produção enxerga — senão o framework passa a recomendar uma forma que a
+ * sua própria auditoria não lê, e as checagens ficam inertes em silêncio.
+ *
+ * A vírgula sobrando é localizada num texto onde o conteúdo das strings também
+ * foi apagado — **com as aspas preservadas**, senão um elemento-string vira
+ * espaço puro e um separador REAL passa por vírgula sobrando (o defeito B4) —
+ * e só então removida do texto real: uma vírgula dentro de `"a,}"` é dado.
+ *
+ * **Um comentário de bloco não fechado LANÇA**, e a razão é a mesma que fez
+ * esta função existir: paridade com o leitor de produção. `JsonCommentHandling.Skip`
+ * do .NET lança nesse caso, e ser mais frouxo que o kit é o defeito INVERSO do
+ * B1 — auditar, e aprovar, um documento que a aplicação recusa carregar.
+ * `readJsonSafe` captura e devolve `null`, que o relatório traduz em
+ * "não verificado" com razão.
+ *
+ * @param {string} raw
+ * @returns {string} JSON estrito, do mesmo comprimento do original
+ * @throws {SyntaxError} comentário de bloco aberto e nunca fechado
+ */
+export function jsoncToJson(raw) {
+  const report = {};
+  const noComments = stripComments(raw, { report }).split('');
+  if (report.unterminated === 'block-comment') {
+    throw new SyntaxError(
+      'JSONC inválido: comentário de bloco `/*` aberto e nunca fechado — '
+      + '`JsonCommentHandling.Skip` do leitor de produção recusa este documento, e a auditoria '
+      + 'não pode aprovar o que a aplicação não carrega.');
+  }
+  const masked = stripComments(raw, { blankStrings: true });
+
+  for (let i = 0; i < masked.length; i++) {
+    if (masked[i] !== ',') continue;
+    let j = i + 1;
+    while (j < masked.length && /\s/.test(masked[j])) j++;
+    if (masked[j] === '}' || masked[j] === ']') noComments[i] = ' ';
+  }
+
+  return noComments.join('');
+}

package/src/lib/ai/pin-drift.js

@@ -0,0 +1,138 @@
+/**
+ * pin-drift.js — o pin de pacotes de IA (`framework/ai-pin.json`) contra o que
+ * o `.csproj` do projeto declara.
+ *
+ * É a ÚNICA das cinco checagens do `doctor --ai` que produz `error`, e só na
+ * faixa flutuante. O motivo é prejuízo medido, não estética: uma faixa `2.*`
+ * sobe sozinha para uma versão com assinatura mudada e o `MissingMethodException`
+ * chega DEPOIS de a chamada ao modelo ter sido paga. As outras quatro checagens
+ * informam — uma checagem que grita em código correto é desligada pelo usuário
+ * na primeira semana.
+ *
+ * O pin é lido por `readAiPin` (#92), nunca por um segundo leitor: duas cópias
+ * do mesmo fato divergem, e é para isso que a Dependency Matrix existe.
+ */
+
+import { join } from 'node:path';
+import { readAiPin } from '../standards/verified-against.js';
+
+/**
+ * Resolve o pin para um projeto, sem NUNCA lançar.
+ *
+ * Ordem: (1) `<target>/.morph/framework/ai-pin.json` — a régua com que aquele
+ * projeto foi instalado; (2) o pin do pacote da CLI. Nenhum dos dois resolve →
+ * `null`, que o relatório traduz em "não verificado". Falta de régua é ausência
+ * de dado, nunca defeito do projeto: é literalmente o estado de todo projeto
+ * cujo framework é anterior ao pin.
+ *
+ * @param {string} targetPath - raiz do projeto
+ * @returns {{ pinnedAt: string, packages: Record<string, {version: string}> } | null}
+ */
+export function resolveAiPin(targetPath) {
+  const roots = [];
+  if (targetPath) roots.push(join(targetPath, '.morph'));
+  roots.push(undefined); // root default de readAiPin = pacote da CLI
+
+  for (const root of roots) {
+    try {
+      const pin = root === undefined ? readAiPin() : readAiPin(root);
+      if (pin && pin.packages && Object.keys(pin.packages).length > 0) return pin;
+    } catch {
+      // Ausente ou inválido nesta raiz — tenta a próxima.
+    }
+  }
+  return null;
+}
+
+/**
+ * Compara a varredura do projeto com o pin.
+ *
+ * Três classes de achado, e a diferença entre elas é de quem é o defeito:
+ *
+ * | classe | severidade | de quem é |
+ * |---|---|---|
+ * | pacote do pin declarado com faixa flutuante | `error` | do projeto |
+ * | pacote do pin declarado com versão fixa ≠ pin | `warn` | do projeto |
+ * | pacote de IA presente no projeto e ausente do pin | `warn` | **do pin** (lacuna) |
+ *
+ * A terceira classe é descrita como lacuna do PIN de propósito: medido,
+ * `Microsoft.Agents.AI.OpenAI` aparece em três repositórios do acervo e não
+ * está no pin. Acusar o projeto ali seria acusar o certo pelo errado.
+ *
+ * @param {object} params
+ * @param {ReturnType<import('./ai-project-scan.js').scanAiPackageRefs>} params.scan
+ * @param {ReturnType<typeof resolveAiPin>} params.pin
+ * @returns {null | Array<{ id: string, severity: 'error'|'warn', package: string, message: string }>}
+ *   `null` = não pude perguntar (sem varredura ou sem pin).
+ */
+export function auditPinDrift({ scan, pin } = {}) {
+  if (!scan || !pin || !pin.packages) return null;
+
+  const findings = [];
+  const pinned = pin.packages;
+
+  for (const pkg of scan.packages) {
+    const pinEntry = pinned[pkg.name];
+
+    if (!pinEntry) {
+      if (!pkg.ai) continue;
+      findings.push({
+        id: 'pin-gap',
+        severity: 'warn',
+        package: pkg.name,
+        message: `\`${pkg.name}\` é pacote de IA declarado pelo projeto e NÃO está em `
+          + `framework/ai-pin.json (pin de ${pin.pinnedAt}). Isto é lacuna do PIN, não defeito `
+          + `do projeto: não há régua para julgar a versão declarada (${pkg.declared ?? 'não declarada'}).`,
+      });
+      continue;
+    }
+
+    if (pkg.versionKind === 'floating') {
+      findings.push({
+        id: 'floating-range',
+        severity: 'error',
+        package: pkg.name,
+        message: `\`${pkg.name}\` está declarado como faixa flutuante \`${pkg.declared}\`; `
+          + `o pin fixa ${pinEntry.version}. Uma faixa sobe sozinha para uma versão com `
+          + `assinatura mudada e o MissingMethodException chega DEPOIS de a chamada ser paga. `
+          + `Fixe a versão.`,
+      });
+      continue;
+    }
+
+    if (pkg.versionKind === 'fixed' && pkg.version !== pinEntry.version) {
+      findings.push({
+        id: 'version-mismatch',
+        severity: 'warn',
+        package: pkg.name,
+        message: `\`${pkg.name}\`: projeto declara ${pkg.version}, pin declara ${pinEntry.version} `
+          + `(pin de ${pin.pinnedAt}).`,
+      });
+      continue;
+    }
+
+    if (pkg.versionKind === 'unresolved') {
+      findings.push({
+        id: 'version-unresolved',
+        severity: 'warn',
+        package: pkg.name,
+        message: `\`${pkg.name}\` tira a versão da propriedade MSBuild \`${pkg.declared}\`, que `
+          + `esta varredura não resolve — não verificado contra o pin (${pinEntry.version}). `
+          + `Chutar o valor seria inventar o dado.`,
+      });
+      continue;
+    }
+
+    if (pkg.versionKind === 'absent') {
+      findings.push({
+        id: 'version-absent',
+        severity: 'warn',
+        package: pkg.name,
+        message: `\`${pkg.name}\` é referenciado sem versão e sem entrada em `
+          + `Directory.Packages.props; o pin declara ${pinEntry.version}.`,
+      });
+    }
+  }
+
+  return findings;
+}