synthesisui 0.16.337 → 0.16.338

package/dist/doctor/architecture.js

@@ -52,12 +52,98 @@ const SHAPES = [
         describe: (a) => `Every component sits directly under \`${a.root}\`, one folder deep. It is the shape that stays legible longest while a system is small, and the one to revisit when the folder passes about forty names.`,
     },
 ];
+/**
+ * A MESMA ORGANIZAÇÃO VISTA DE MAIS PERTO NÃO É UMA SEGUNDA ESCOLHA (`INV-COB-09`).
+ *
+ * O QUE O CLIENTE GANHA: a pergunta "qual organização tem PRIORIDADE" só lhe oferece
+ * organizações que disputam de verdade. Sem isto ele escolhe entre uma escada atômica e uma
+ * pasta que mora DENTRO dela - a mesma organização, medida de duas distâncias -, e qualquer
+ * resposta que ele der é a mesma resposta. Uma pergunta cujas opções não se excluem não é uma
+ * pergunta: é um formulário que ele preenche sem que nada mude no que os agentes dele escrevem.
+ *
+ * A PROPRIEDADE: uma organização é reconhecida no lugar mais RASO que a explica. Uma forma é a
+ * mesma organização vista de mais perto quando é do MESMO tipo de uma que já a cobre, ou quando é
+ * a leitura genérica (`flat`) de um lugar que outra forma já nomeia com mais informação. Formas de
+ * tipos DIFERENTES descrevem fatos diferentes, e nenhuma apaga a outra - o peso (`MINOR_SHARE`) já
+ * decide qual delas pede decisão e qual é dita como canto.
+ *
+ * O DESEMPATE NO MESMO ROOT continua sendo só o de `flat`, e ele não muda aqui: duas formas
+ * específicas na mesma pasta (`layered` e `colocated` em `src`, por exemplo) são duas leituras
+ * legítimas do mesmo lugar, e escolher entre elas é justamente a decisão que a pergunta existe
+ * para pedir. `flat` é a forma mais permissiva das cinco - basta uma pasta `components` -, então
+ * onde uma específica também casa, ela é a mesma coisa dita com menos informação.
+ *
+ * MEDIÇÃO de 31/08 - população e régua de enumeração de escopo escritas UMA vez em
+ * `contracts/camada-4-cobertura.md` (`INV-COB-09`), e não recopiadas aqui: 65 formas reconhecidas
+ * em 43 escopos passam a 56; as 9 subordinadas dizem o mesmo fato de um ancestral, e estão em 6
+ * escopos. Foto daquelas populações naquele dia, nunca invariante.
+ */
+export function dropShapesAlreadyExplained(found) {
+    return found.filter((a) => !found.some((b) => b !== a && explains(b, a)));
+}
+/**
+ * `other` é a MESMA organização que `shape`, vista de mais longe?
+ *
+ * A pergunta não é "está por perto": é se as duas dizem o mesmo fato. Uma forma é a mesma
+ * organização vista de mais perto quando é do MESMO tipo de uma que já a cobre, ou quando é a
+ * leitura genérica (`flat`) de um lugar que outra forma já nomeia com mais informação.
+ *
+ * FORMAS DE TIPOS DIFERENTES DESCREVEM FATOS DIFERENTES, e nenhuma apaga a outra - nem quando uma
+ * mora dentro da outra. O layout React mais comum que existe é a prova: `src/{components}` com
+ * `src/components/{atoms, molecules, organisms}` embaixo. Com o ancestral vencendo sempre, a
+ * escada atômica SOME, e o que sobra é a leitura mais pobre das duas - o cliente recebe no
+ * `CLAUDE.md` dele a regra "Every component sits directly under `src`, one folder deep", que é
+ * FALSA no repositório dele, e o caminho `src/{components}`, que manda o agente parar um degrau
+ * antes de onde o componente nasce. Uma opção errada é pior que duas opções: ele nem sabe que
+ * havia o que decidir.
+ *
+ * Quem decide qual das duas pede decisão e qual é dita como canto é o PESO (`MINOR_SHARE`), e não
+ * este predicado - uma escada de 6 arquivos dentro de um `colocated` de 780 continua sendo dita,
+ * e continua não virando pergunta.
+ */
+function explains(other, shape) {
+    if (isUnderPath(other.root, shape.root))
+        return other.kind === shape.kind || shape.kind === "flat";
+    return (pathKey(other.root) === pathKey(shape.root) &&
+        shape.kind === "flat" &&
+        other.kind !== "flat");
+}
+/**
+ * O CAMINHO COMPARÁVEL - a raiz do escopo é escrita `.` pela caminhada, e comparada com `""` ela é
+ * a mesma pasta. Comparar as strings cruas faria a raiz deixar de explicar o que está embaixo
+ * dela, que é o caso mais comum de todos.
+ *
+ * AS DUAS OUTRAS NORMALIZAÇÕES SÃO DEFENSIVAS, e ficam nomeadas como tal: barra final e `./` na
+ * frente não são alcançáveis pela caminhada real - `import.ts` escreve `path || "."` e monta o
+ * resto com `parts.slice(…).join("/")` -, então nenhum teste pode reprová-las por comportamento.
+ * Elas custam duas chamadas de `replace` e protegem quem montar a árvore à mão.
+ */
+function pathKey(path) {
+    const tidy = path.replace(/\/+$/, "").replace(/^\.\//, "");
+    return tidy === "." ? "" : tidy;
+}
+/**
+ * `path` está DENTRO de `ancestor` - por SEGMENTO, nunca por prefixo de texto.
+ *
+ * `"src/ui-kit".startsWith("src/ui")` é verdadeiro e está errado: são duas pastas irmãs, e por
+ * essa comparação uma organização real desapareceria da pergunta sem que nada a explicasse.
+ */
+function isUnderPath(ancestor, path) {
+    const a = pathKey(ancestor);
+    const p = pathKey(path);
+    /**
+     * A MESMA PASTA JÁ CAI FORA POR CONSTRUÇÃO, e por isso não há guarda para ela: com `a === p`,
+     * `p.startsWith(`${a}/`)` é falso (uma pasta não é filha de si mesma) e a raiz cai no `p !== ""`.
+     * Uma guarda a mais aqui seria linha que nenhum caso alcança - e código que nenhum caso alcança
+     * é código que nenhum teste pode reprovar.
+     */
+    return a === "" ? p !== "" : p.startsWith(`${a}/`);
+}
 /**
  * Which shapes this tree actually has, ranked by how much code each holds.
  *
- * `flat` is checked last and only reported when nothing more specific matched under the
- * same root: a `components/` folder inside an atomic library is not a second
- * architecture, it is the same one seen from further away.
+ * O que sobra é o que governa código que nenhuma outra forma já governa - a subordinação inteira
+ * mora em `dropShapesAlreadyExplained` (`INV-COB-09`), numa redação só.
  */
 export function detectArchitectures(entries) {
     const found = [];
@@ -76,10 +162,6 @@ export function detectArchitectures(entries) {
             }
             if (!complete)
                 continue;
-            if (shape.kind === "flat" &&
-                found.some((f) => f.root === entry.path && f.kind !== "flat")) {
-                continue;
-            }
             found.push({
                 kind: shape.kind,
                 root: entry.path,
@@ -88,10 +170,7 @@ export function detectArchitectures(entries) {
             });
         }
     }
-    return found
-        .filter((a) => a.kind !== "flat" ||
-        !found.some((b) => b.root === a.root && b.kind !== "flat"))
-        .sort((a, b) => b.files - a.files || a.root.localeCompare(b.root));
+    return dropShapesAlreadyExplained(found).sort((a, b) => b.files - a.files || a.root.localeCompare(b.root));
 }
 /** The sentence that becomes the rule. Written for an agent about to add a file. */
 export function describeArchitecture(a) {

package/dist/install-marks.js

@@ -389,7 +389,33 @@ export const CHECKER_SINCE = "0.16.308";
  * nenhum dos 43 escopos medidos, então ninguém recebe uma organização DIFERENTE - só o número
  * honesto.
  */
-export const READER_SINCE = "0.16.337";
+/**
+ * 0.16.337 -> 0.16.338 em 31/08 (`INV-COB-09`): uma organização passou a ser reconhecida no lugar
+ * mais RASO que a explica. Uma forma do MESMO tipo de outra que já a cobre, ou a leitura genérica
+ * de um lugar que outra já nomeia com mais informação, deixa de ser gravada como uma segunda
+ * organização. Tipos DIFERENTES continuam os dois gravados: eles dizem fatos diferentes sobre o
+ * mesmo código, e apagar o de dentro entregaria a leitura mais pobre como se fosse a única.
+ *
+ * A marca sobe porque um censo já gravado carrega as entradas duplicadas e não há como saber quais
+ * eram subordinadas sem reler a árvore do disco: a subordinação se decide comparando os CAMINHOS
+ * medidos, e um censo antigo guarda o que foi reconhecido, não a caminhada que o reconheceu. Só a
+ * remedição lê o disco.
+ *
+ * O QUE O `sync` ENTREGA, e o que ele NÃO entrega. Ele remede com `takeCensus`, então o campo
+ * `architectures` do censo é reescrito sem as entradas subordinadas e o censo reenviado já chega
+ * limpo. Ele NÃO reimprime a seção de organização no terminal - essa seção é do relatório de
+ * `import` -, e NÃO reescreve a regra no `CLAUDE.md` dele: aquela linha nasce da conversa de
+ * import, que lê `architectures[].rule` do censo, e `rulesFromCensus` não olha para este campo.
+ * Quem já tem a regra escrita a partir de uma organização subordinada continua com ela até um
+ * import novo, e dizer o contrário seria prometer que um comando conserta o que ele não conserta.
+ *
+ * MEDIÇÃO de 31/08 - população e régua de enumeração de escopo em
+ * `contracts/camada-4-cobertura.md` (`INV-COB-09`): 65 formas reconhecidas em 43 escopos passam a
+ * 56; as 9 subordinadas dizem o mesmo fato de um ancestral, e estão em 6 escopos. O hash do corpus
+ * NÃO se moveu, e isso é a informação: nenhum dos 28 apps dourados tem forma repetindo o que uma
+ * ancestral já diz, então a estabilidade ali prova ausência de regressão e não ausência de efeito.
+ */
+export const READER_SINCE = "0.16.338";
 /**
  * O QUE ESTÁ INSTALADO AQUI FICOU PARA TRÁS - e as DUAS condições que fazem isso ser verdade.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.337",
+  "version": "0.16.338",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {