@noeva/analytics-core 0.3.3 → 0.4.0

package/contenuto/lib/modello/pubblica.py

@@ -60,11 +60,17 @@ def versione_di(radice: pathlib.Path) -> str:
 
 
 def estrai_da_head(radice: pathlib.Path, dest: pathlib.Path) -> None:
-    """I file del modello com'erano nel commit, senza toccare il disco del repository."""
-    presenti = [p for p in [*FILE_MODELLO, "consegna.yml"] if git(radice, "ls-tree", "--name-only", "HEAD", p).strip()]
+    """I file del modello com'erano nel commit, senza toccare il disco del repository.
+
+    Con loro quelli da cui si genera la scheda del progetto (scheda.py): analytics.json
+    e le index.html di apps/, per il titolo del progetto e delle dashboard."""
+    presenti = [p for p in [*FILE_MODELLO, "consegna.yml", "analytics.json"]
+                if git(radice, "ls-tree", "--name-only", "HEAD", p).strip()]
     mancanti = {"wren_project.yml", "relationships.yml", "models"} - set(presenti)
     if mancanti:
         raise SystemExit(f"nel commit mancano {sorted(mancanti)}: non e' il repository di un progetto con un modello")
+    presenti += [p for p in git(radice, "ls-tree", "-r", "--name-only", "HEAD", "apps").splitlines()
+                 if p.count("/") <= 2 and p.endswith("/index.html")]
     archivio = subprocess.run(["git", "archive", "--format=tar", "HEAD", *presenti], cwd=radice,
                               check=True, capture_output=True).stdout
     with tempfile.TemporaryFile() as t:

package/contenuto/lib/modello/scheda.py

@@ -0,0 +1,146 @@
+"""La scheda del progetto: la regola knowledge/rules/00-progetto.md, generata (NW-1286).
+
+Il plugin noeva-analytics porta il metodo, uguale per tutti; il server MCP del
+progetto porta cio' che e' vero del progetto (NW-1261). La scheda e' la parte di
+quel vero che serve prima di ogni domanda: di chi sono i dati, cosa coprono,
+dove stanno le dashboard, chi e' il contatto in 4D. La skill `analisi` la trova
+con get_instructions.
+
+Si genera dal repository del progetto, mai a mano: modello_di_consegna (consegna.py)
+la scrive nel modello che si consegna, e da li' arriva uguale al modello pubblicato
+su R2, al servizio locale che compila il repository aperto e alla cartella
+consegnata. Nel repository non c'e': una scheda in git sarebbe una copia da tenere
+allineata, e prima o poi qualcuno la ritoccherebbe.
+
+Legge, tutti facoltativi tranne analytics.json:
+
+    analytics.json          l'id del progetto
+    consegna.yml            cliente, descrizione, contatto_4d, la `cosa` di ogni sorgente,
+                            modello_r2.url (il contenitore, default https://analytics.noeva.ai)
+    wren_project.yml        il tipo di database
+    models/                 quanti modelli
+    apps/index.html         il titolo del progetto, che e' quello dell'indice
+    apps/*/index.html       le dashboard, col titolo della pagina
+
+Il registro dei progetti (lib/rilascio/progetti.json) sta nel monorepo di 4D e il
+repository di un cliente non lo vede (il pacchetto non nomina clienti, ADR 0005):
+la scheda dice solo cio' che il repository del progetto sa di se'.
+
+Nessuna data e nessuna versione dentro: la stessa sorgente da' la stessa scheda,
+byte per byte, da qualunque strada passi.
+
+    python3 lib/modello/scheda.py <repository>      stampa la scheda
+"""
+from __future__ import annotations
+
+import html
+import json
+import pathlib
+import re
+import sys
+
+import yaml
+
+FILE = "00-progetto.md"
+CONTENITORE = "https://analytics.noeva.ai"
+# Le cartelle di apps/ che non sono dashboard: il motore e i moduli di pagina.
+NON_DASHBOARD = {"assets", "dati", "vendor"}
+TITOLO = re.compile(r"<title>(.*?)</title>", re.S | re.I)
+
+
+def _leggi_yaml(p: pathlib.Path) -> dict:
+    return (yaml.safe_load(p.read_text(encoding="utf-8")) or {}) if p.is_file() else {}
+
+
+def _titolo(p: pathlib.Path) -> str | None:
+    if not p.is_file():
+        return None
+    m = TITOLO.search(p.read_text(encoding="utf-8", errors="replace"))
+    return " ".join(html.unescape(m.group(1)).split()) if m else None
+
+
+def identificativo(sorgente: pathlib.Path) -> str:
+    """L'id del progetto: analytics.json, o il nome della cartella project-<id> del monorepo."""
+    f = sorgente / "analytics.json"
+    if f.is_file():
+        return json.loads(f.read_text(encoding="utf-8"))["progetto"]
+    return sorgente.name.removeprefix("project-")
+
+
+def dashboard(sorgente: pathlib.Path) -> list[tuple[str, str]]:
+    """(cartella, titolo) delle dashboard in apps/, in ordine di cartella."""
+    apps = sorgente / "apps"
+    if not apps.is_dir():
+        return []
+    esito = []
+    for d in sorted(p for p in apps.iterdir() if p.is_dir() and p.name not in NON_DASHBOARD):
+        t = _titolo(d / "index.html")
+        if t:
+            esito.append((d.name, t))
+    return esito
+
+
+def scheda(sorgente: pathlib.Path, conf: dict | None = None) -> str:
+    """Il testo di 00-progetto.md per il repository in `sorgente`.
+
+    `conf` e' consegna.yml intero (default: quello di `sorgente`); chi costruisce
+    con un'altra configurazione (costruisci.py --config) la passa qui."""
+    conf = _leggi_yaml(sorgente / "consegna.yml") if conf is None else conf
+    ident = identificativo(sorgente)
+    progetto = _leggi_yaml(sorgente / "wren_project.yml")
+    titolo = _titolo(sorgente / "apps" / "index.html")
+    cliente = conf.get("cliente") or titolo or ident
+    base = f"{((conf.get('modello_r2') or {}).get('url') or CONTENITORE).rstrip('/')}/{ident}/"
+    modelli = sorted(p.parent.name for p in (sorgente / "models").glob("*/metadata.yml"))
+    sorgenti = [(k, s.get("cosa")) for k, s in (conf.get("sorgenti") or {}).items() if s.get("cosa")]
+
+    r = [
+        f"# Il progetto: {cliente}",
+        "",
+        "Scheda generata dal repository del progetto insieme al modello che si consegna:",
+        "non si scrive a mano e si rigenera con il modello. Dice di chi sono i dati, cosa",
+        "coprono, dove stanno le dashboard e chi e' il contatto in 4D; cosa significano i",
+        "numeri lo dicono le altre regole.",
+        "",
+        f"- **Cliente**: {cliente}",
+        f"- **Progetto NOEVA Analytics**: `{ident}`" + (f", «{titolo}»" if titolo and titolo != cliente else ""),
+    ]
+    if conf.get("descrizione"):
+        r.append(f"- **In breve**: {' '.join(str(conf['descrizione']).split())}")
+    r += ["", "## Cosa coprono i dati", ""]
+    if len(sorgenti) == 1:
+        r.append(f"- {sorgenti[0][1]}")
+    else:
+        r += [f"- `{k}`: {cosa}" for k, cosa in sorgenti]
+    db = progetto.get("data_source")
+    r.append(f"- Il modello: {len(modelli)} modelli" + (f" su {db}" if db else "")
+             + "; l'elenco con list_models, il significato con describe_model.")
+    if not sorgenti:
+        r.append("- La copertura per sorgente non e' descritta (`cosa` in consegna.yml): la dicono "
+                 "le regole e la descrizione dei modelli.")
+
+    r += ["", "## Le dashboard", "",
+          "Dietro il login NOEVA: le apre chi ha il progetto nel suo workspace.", "",
+          f"- Indice: {base}"]
+    r += [f"- {t}: {base}{cartella}/" for cartella, t in dashboard(sorgente)]
+
+    r += ["", "## Il contatto in 4D", ""]
+    contatto = conf.get("contatto_4d")
+    if contatto:
+        r.append(f"- {' '.join(str(contatto).split())}")
+    else:
+        r.append("- Non indicato (`contatto_4d` in consegna.yml).")
+    r.append("- Per scrivere a 4D (una quadratura che non torna, una modifica) c'e' la Richiesta a 4D.")
+    return "\n".join(r) + "\n"
+
+
+def scrivi(sorgente: pathlib.Path, rules: pathlib.Path, conf: dict | None = None) -> pathlib.Path:
+    """Scrive la scheda in `rules`/00-progetto.md, sopra un'eventuale copia a mano."""
+    rules.mkdir(parents=True, exist_ok=True)
+    f = rules / FILE
+    f.write_text(scheda(sorgente, conf), encoding="utf-8")
+    return f
+
+
+if __name__ == "__main__":
+    sys.stdout.write(scheda(pathlib.Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()))

package/contenuto/lib/snapshot/ai.py

@@ -40,12 +40,18 @@ def carica_commento(progetto: pathlib.Path):
     modulo = importlib.util.module_from_spec(spec)
     sys.path.insert(0, str(progetto))
     spec.loader.exec_module(modulo)
-    for nome in ("istruzioni", "conoscenza", "MODI", "SCHEMA", "LINGUE"):
+    for nome in ("conoscenza", "LINGUE"):
         if not hasattr(modulo, nome):
             raise SystemExit(f"{progetto.name}/commento.py non ha {nome}: non e' allineato allo standard")
     return modulo
 
 
+def ha_tour(c) -> bool:
+    """Il commento guidato e' facoltativo: un progetto con la sola chat ha in
+    commento.py la conoscenza ma non istruzioni, modi e schema del tour."""
+    return all(hasattr(c, nome) for nome in ("istruzioni", "MODI", "SCHEMA"))
+
+
 def istruzioni_sito(chat, lingua: str) -> str:
     """Le istruzioni della chat per il sito: li' ha solo run_sql sullo snapshot, non recall_queries,
     quindi senza la riga della memoria delle domande confermate (GUIDA_MEMORIA di chat.py)."""
@@ -84,7 +90,7 @@ def main(argv: list[str]) -> int:
     uscita.mkdir(parents=True, exist_ok=True)
     adesso = dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds")
     scritti = 0
-    for pagina in pagine(progetto):
+    for pagina in pagine(progetto) if ha_tour(c) else []:
         for lingua in c.LINGUE:
             sistema = c.istruzioni(lingua) + "\n\n# Knowledge base del progetto\n\n" + c.conoscenza(pagina)
             (uscita / f"commento-{pagina}.{lingua}.json").write_text(json.dumps(
@@ -104,6 +110,8 @@ def main(argv: list[str]) -> int:
                      "generato": adesso},
                     ensure_ascii=False, indent=1) + "\n", encoding="utf-8")
                 n_chat += 1
+    if not scritti and not n_chat:
+        raise SystemExit(f"{progetto.name}: ne' commento guidato ne' chat, nessun prompt da scrivere")
     print(f"  apps/dati/ai: {scritti} prompt del commento, {n_chat} della chat ({len(c.LINGUE)} lingue)")
     return 0
 

package/contenuto/lib/snapshot/esporta.py

@@ -101,6 +101,8 @@ import pyarrow as pa
 import pyarrow.parquet as pq
 import yaml
 
+from manifesto import id_progetto
+
 ROMA = ZoneInfo("Europe/Rome")
 
 
@@ -403,7 +405,8 @@ def main(argv: list[str]) -> int:
     adesso = dt.datetime.now(ROMA).isoformat(timespec="seconds")
     costanti = {**(conf.get("costanti") or {}), **opt["costanti"]}
     manifesto = {
-        "progetto": progetto.name.removeprefix("project-"),
+        # l'id nel contenitore (`<id>`, non la cartella): la Vista della pagina lo dichiara (standard §5)
+        "progetto": id_progetto(progetto),
         "generato": adesso,
         "data_del_dato": data_del_dato,
         "sorgente": sorgente,

package/contenuto/lib/snapshot/manifesto.py

@@ -19,6 +19,27 @@ import pathlib
 import sys
 
 
+def id_progetto(cartella: pathlib.Path) -> str:
+    """L'id del progetto nel contenitore (`<id>`), non il nome della cartella.
+
+    Il repository di un progetto (ADR 0005) lo scrive in analytics.json, alla sua
+    radice: si cerca risalendo da `cartella` (il progetto, o la sua apps/dati).
+    Senza, il nome della cartella del progetto senza il prefisso: `project-<id>`
+    nel monorepo, `noeva-analytics-<id>` per un clone del repository, `<id>` per
+    il pacchetto del worker."""
+    cartella = cartella.resolve()
+    for d in (cartella, *cartella.parents):
+        f = d / "analytics.json"
+        if f.is_file():
+            voce = json.loads(f.read_text(encoding="utf-8")).get("progetto")
+            if voce:
+                return voce
+            break
+    if cartella.name == "dati" and cartella.parent.name == "apps":
+        cartella = cartella.parent.parent
+    return cartella.name.removeprefix("project-").removeprefix("noeva-analytics-")
+
+
 def main(argv: list[str]) -> int:
     if len(argv) < 2:
         print(__doc__)
@@ -36,7 +57,8 @@ def main(argv: list[str]) -> int:
             generato = json.loads(f.read_text(encoding="utf-8")).get("generato")
             data_del_dato = str(generato)[:10] if generato else None
     generato = dt.datetime.fromtimestamp(piu_recente).astimezone().isoformat(timespec="seconds")
-    manifesto = {"generato": generato, "data_del_dato": data_del_dato or generato[:10], "file": voci}
+    manifesto = {"progetto": id_progetto(cartella), "generato": generato,
+                 "data_del_dato": data_del_dato or generato[:10], "file": voci}
     (cartella / "snapshot.json").write_text(json.dumps(manifesto, ensure_ascii=False, indent=1), encoding="utf-8")
     print(f"  snapshot.json: {len(voci)} file, dato al {manifesto['data_del_dato']}")
     return 0

package/core.js

@@ -247,6 +247,17 @@ export function verifica(radice, config) {
     errori.push(`file gestito ${d.stato}: ${d.percorso} — lo riscrive \`analytics upgrade\`, o va in non_gestiti`);
   }
 
+  // Le risposte alle domande si registrano in un modo solo (standard §6.4): la
+  // pagina del progetto che mostra le domande usa risposte.js, che salva sul Mac,
+  // online dietro il cancello, e dove non si salva esporta su file.
+  const paginaProgetto = join(radice, 'apps', 'progetto');
+  if (existsSync(paginaProgetto)) {
+    const testi = fileSotto(paginaProgetto).filter((f) => /\.(html|js)$/.test(f)).map((f) => readFileSync(f, 'utf8'));
+    if (testi.some((x) => x.includes('lista-domande')) && !testi.some((x) => x.includes('montaRisposte'))) {
+      errori.push('apps/progetto mostra le domande ma non registra le risposte con montaRisposte di apps/assets/risposte.js (standard §6.4)');
+    }
+  }
+
   const tracciati = trackedDaGit(radice);
   if (tracciati) {
     for (const f of tracciati) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noeva/analytics-core",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Gli strumenti di un progetto NOEVA Analytics nel suo repository: moduli di pagina, snapshot, verifica dello standard e kit dell'agente (ADR 0005).",
   "type": "module",
   "bin": {