Files
Febe/src/Febe.Core/Collection/Readers/ReaderVocabulary.cs
T
Alby96andClaude Opus 5.5 9941a2fa1f
verifica / controlli (push) Successful in 20s
verifica / prove (push) Failing after 19m40s
verifica / installatore (push) Skipped
verifica / immagine (push) Skipped
Ricerca dei profili con suggerimenti e foto (#37)
«Aggiungi account» ha una sola casella: mentre Alberto scrive compaiono
subito i suggerimenti locali, poi i profili di Instagram con la foto, come
chiesto in #37. Il browser di Febe scrive nella casella «Cerca» di Instagram
con tasti veri da una mappa chiusa (mai Invio, Tab o Esc), controlla prima
il fuoco, legge la risposta della pagina e non clicca mai un risultato.

La ricerca ha una categoria propria nel Governatore, con tetti larghi che
non consumano quelli della raccolta, e si dà il turno con il motore
sull'unica pagina; a fine sessione la pagina torna comunque al riposo. Le
foto passano dal CDN con un permesso ciascuna e restano solo in memoria.

Le risposte di Alberto del 15 novembre (controllo del fuoco, turni, evento
requestWillBeSent, niente foto dei seguiti per ora) sono in §6.1 e in
docs/decisioni.md. Su Instagram vero la ricerca parte quando i bersagli
search-open e search-box saranno raccolti dal vivo.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 16:30:03 +01:00

541 lines
20 KiB
C#

using System.Text.Json;
using System.Text.Json.Serialization;
namespace Febe.Core.Collection.Readers;
/// <summary>
/// One concept of the vocabulary: the keys (or dotted paths, e.g. «image_versions2.candidates») under which a site
/// puts a piece of data. Empty means «not known yet».
/// </summary>
public sealed record VocabularyKeys(IReadOnlyList<string> Paths)
{
public static VocabularyKeys None { get; } = new([]);
public bool IsSet => Paths.Count > 0;
/// <summary>Each path split into its segments.</summary>
internal IReadOnlyList<string[]> Segments { get; } = [.. Paths.Select(p => p.Split('.', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))];
/// <summary>Looks the concept up in <paramref name="node"/>: the first path that exists wins.</summary>
public bool TryGet(JsonElement node, out JsonElement value)
{
if (node.ValueKind == JsonValueKind.Object)
{
foreach (var segments in Segments)
{
var current = node;
var found = true;
foreach (var segment in segments)
{
if (current.ValueKind != JsonValueKind.Object || !current.TryGetProperty(segment, out current))
{
found = false;
break;
}
}
if (found && current.ValueKind is not (JsonValueKind.Null or JsonValueKind.Undefined))
{
value = current;
return true;
}
}
}
value = default;
return false;
}
/// <summary>True when the first segment of one of the paths is a property of <paramref name="node"/>.</summary>
public bool Has(JsonElement node) => TryGet(node, out _);
public override string ToString() => Paths.Count == 0 ? "(non impostato)" : string.Join(" | ", Paths);
}
/// <summary>Keys of a content node: a post, a story, an item of a highlight collection, or a file of a series.</summary>
public sealed record ContentKeys
{
public VocabularyKeys Id { get; init; } = VocabularyKeys.None;
public VocabularyKeys Code { get; init; } = VocabularyKeys.None;
/// <summary>Publication time: a number (Unix seconds, or milliseconds when very large) or an ISO 8601 text.</summary>
public VocabularyKeys TakenAt { get; init; } = VocabularyKeys.None;
public VocabularyKeys Caption { get; init; } = VocabularyKeys.None;
/// <summary>The image versions: an array of version objects (or a single one).</summary>
public VocabularyKeys Images { get; init; } = VocabularyKeys.None;
/// <summary>The video versions: an array of version objects (or a single one).</summary>
public VocabularyKeys Videos { get; init; } = VocabularyKeys.None;
/// <summary>The files of a series, in order: each one is a content node without its own date.</summary>
public VocabularyKeys Children { get; init; } = VocabularyKeys.None;
/// <summary>How many files the series declares: when more than the children received, the data is incomplete.</summary>
public VocabularyKeys ChildCount { get; init; } = VocabularyKeys.None;
/// <summary>The author: a profile node.</summary>
public VocabularyKeys Owner { get; init; } = VocabularyKeys.None;
/// <summary>True for content pinned on top of a profile (not «already known» for the stop rule).</summary>
public VocabularyKeys Pinned { get; init; } = VocabularyKeys.None;
/// <summary>When a story stops being available (a date, as for <see cref="TakenAt"/>).</summary>
public VocabularyKeys ExpiresAt { get; init; } = VocabularyKeys.None;
/// <summary>Video duration in seconds (on the node or on the video version).</summary>
public VocabularyKeys Duration { get; init; } = VocabularyKeys.None;
}
/// <summary>Keys of one version of a file (one size of an image, one rendition of a video).</summary>
public sealed record VersionKeys
{
public VocabularyKeys Url { get; init; } = VocabularyKeys.None;
public VocabularyKeys Width { get; init; } = VocabularyKeys.None;
public VocabularyKeys Height { get; init; } = VocabularyKeys.None;
/// <summary>For videos: true when the rendition carries audio and video together (spec §6.5 point 1).</summary>
public VocabularyKeys HasAudio { get; init; } = VocabularyKeys.None;
}
/// <summary>Keys of a profile node.</summary>
public sealed record ProfileKeys
{
public VocabularyKeys Id { get; init; } = VocabularyKeys.None;
public VocabularyKeys Username { get; init; } = VocabularyKeys.None;
public VocabularyKeys DisplayName { get; init; } = VocabularyKeys.None;
public VocabularyKeys IsPrivate { get; init; } = VocabularyKeys.None;
/// <summary>True when Alberto follows the profile.</summary>
public VocabularyKeys IsFollowed { get; init; } = VocabularyKeys.None;
public VocabularyKeys PostCount { get; init; } = VocabularyKeys.None;
/// <summary>Profile picture: a version object, an array of versions or an address.</summary>
public VocabularyKeys Picture { get; init; } = VocabularyKeys.None;
/// <summary>When the latest active story was published (stories bar, H2).</summary>
public VocabularyKeys LatestStoryAt { get; init; } = VocabularyKeys.None;
}
/// <summary>Keys of a highlight collection node.</summary>
public sealed record HighlightKeys
{
public VocabularyKeys Id { get; init; } = VocabularyKeys.None;
public VocabularyKeys Title { get; init; } = VocabularyKeys.None;
public VocabularyKeys Owner { get; init; } = VocabularyKeys.None;
/// <summary>The contents of the collection, when the response carries them.</summary>
public VocabularyKeys Items { get; init; } = VocabularyKeys.None;
/// <summary>The cover image of the collection, read as a version.</summary>
public VocabularyKeys Cover { get; init; } = VocabularyKeys.None;
}
/// <summary>Keys of the pagination information that comes with a page of data.</summary>
public sealed record PageKeys
{
public VocabularyKeys HasMore { get; init; } = VocabularyKeys.None;
/// <summary>Opaque resume point given by the site (the backfill stores it).</summary>
public VocabularyKeys Cursor { get; init; } = VocabularyKeys.None;
}
/// <summary>
/// Keys of the answer of the site's own search box (issue #37). The search carries its own profile keys, so a site
/// whose other concepts use other keys can still serve the search in its own shape. Only profiles are read: hashtags
/// and places are ignored.
/// </summary>
public sealed record SearchKeys
{
/// <summary>The key of the search answer: found anywhere in the tree, its value holds <see cref="Items"/>.</summary>
public VocabularyKeys Root { get; init; } = VocabularyKeys.None;
/// <summary>The list of profile results under the root.</summary>
public VocabularyKeys Items { get; init; } = VocabularyKeys.None;
/// <summary>Order of an item in the list (array order when missing).</summary>
public VocabularyKeys Position { get; init; } = VocabularyKeys.None;
/// <summary>The profile node of an item.</summary>
public VocabularyKeys Profile { get; init; } = VocabularyKeys.None;
public VocabularyKeys Id { get; init; } = VocabularyKeys.None;
public VocabularyKeys Username { get; init; } = VocabularyKeys.None;
public VocabularyKeys DisplayName { get; init; } = VocabularyKeys.None;
/// <summary>The profile picture: the first key present wins (the small one is enough for a suggestion).</summary>
public VocabularyKeys Picture { get; init; } = VocabularyKeys.None;
public VocabularyKeys Verified { get; init; } = VocabularyKeys.None;
/// <summary>True when the reader can recognize a search answer.</summary>
public bool IsSet => Root.IsSet && Items.IsSet && Id.IsSet && Username.IsSet;
}
/// <summary>Whether the vocabulary is confirmed on real samples or still a hypothesis (spec §6.4, rule 10).</summary>
public enum VocabularyStatus
{
Confirmed,
/// <summary>Hints only, to be confirmed with the M0 samples: recipes refuse to use it.</summary>
Hypothesis,
}
/// <summary>
/// The key vocabulary of one site (<c>lettori.instagram.json</c>, <c>lettori.prova.json</c>): which keys mean what.
/// The reader finds data by shape, wherever it is in the response; the vocabulary only names the keys, so it can be
/// updated without recompiling when the site changes (spec §6.4).
/// </summary>
public sealed record ReaderVocabulary
{
public required string Site { get; init; }
public VocabularyStatus Status { get; init; } = VocabularyStatus.Hypothesis;
public string? Note { get; init; }
/// <summary>Where it was loaded from, for messages.</summary>
public string? Source { get; init; }
public ContentKeys Content { get; init; } = new();
public VersionKeys Version { get; init; } = new();
public ProfileKeys Profile { get; init; } = new();
public HighlightKeys Highlight { get; init; } = new();
public PageKeys Page { get; init; } = new();
/// <summary>
/// The answer of the site's search box (issue #37). Not among <see cref="MissingConcepts"/>: the collection does not
/// depend on it, and without it the search on the site is «da configurare».
/// </summary>
public SearchKeys Search { get; init; } = new();
/// <summary>The key under which the response describes the connected account (H10).</summary>
public VocabularyKeys Viewer { get; init; } = VocabularyKeys.None;
/// <summary>
/// Keys at least one of which, anywhere in a response, makes it «about contents or profiles». A response that has
/// none of them is <see cref="ReadShape.Unrelated"/> and ignored, instead of counting as an unknown shape: a real site
/// sends many JSON answers that have nothing to do with contents (Instagram: promotions, logging, «seen» marks).
/// Plain key names, not paths. Empty: every response counts (the test site, where any unknown answer is a format
/// change).
/// </summary>
public IReadOnlyList<string> Relevance { get; init; } = [];
/// <summary>
/// Concepts the collection pipeline cannot work without, still unset. While this is not empty, or the status is
/// a hypothesis, recipes refuse to run on the site.
/// </summary>
public IReadOnlyList<string> MissingConcepts
{
get
{
var missing = new List<string>();
void Need(VocabularyKeys keys, string name)
{
if (!keys.IsSet)
{
missing.Add(name);
}
}
Need(Content.Id, "content.id");
Need(Content.TakenAt, "content.takenAt");
Need(Content.Images, "content.images");
Need(Content.Videos, "content.videos");
// Without the author nothing tells whose a post is: the giro dei seguiti would save nothing and the profile
// recipes would skip every post, silently.
Need(Content.Owner, "content.owner");
Need(Version.Url, "version.url");
Need(Version.Width, "version.width");
Need(Version.Height, "version.height");
Need(Profile.Id, "profile.id");
Need(Profile.Username, "profile.username");
return missing;
}
}
/// <summary>True when recipes may rely on this vocabulary.</summary>
public bool IsUsable => Status == VocabularyStatus.Confirmed && MissingConcepts.Count == 0;
/// <summary>Italian explanation of why the vocabulary cannot be used yet, or null.</summary>
public string? UnusableReason => IsUsable
? null
: Status == VocabularyStatus.Hypothesis
? $"Il vocabolario dei lettori per «{Site}» è ancora un'ipotesi, da confermare con i campioni di M0 (specifica §6.4, regola 10)."
: $"Il vocabolario dei lettori per «{Site}» è incompleto: mancano {string.Join(", ", MissingConcepts)}.";
/// <summary>The shipped Instagram vocabulary (embedded <c>lettori.instagram.json</c>): hints only.</summary>
public static ReaderVocabulary LoadInstagram() => LoadEmbedded("lettori.instagram.json");
/// <summary>The vocabulary of the local test site (embedded <c>lettori.prova.json</c>).</summary>
public static ReaderVocabulary LoadTestSite() => LoadEmbedded("lettori.prova.json");
/// <summary>Loads <paramref name="path"/> when it exists, otherwise the embedded file with the same name.</summary>
public static ReaderVocabulary LoadOrEmbedded(string? path, string embeddedName) =>
!string.IsNullOrEmpty(path) && File.Exists(path) ? Load(path) : LoadEmbedded(embeddedName);
public static ReaderVocabulary Load(string path) => Parse(File.ReadAllText(path), path);
public static ReaderVocabulary LoadEmbedded(string fileName)
{
var resource = $"Febe.Core.Config.{fileName}";
using var stream = typeof(ReaderVocabulary).Assembly.GetManifestResourceStream(resource)
?? throw new FileNotFoundException($"Risorsa incorporata mancante: {resource}");
using var reader = new StreamReader(stream);
return Parse(reader.ReadToEnd(), fileName);
}
public static ReaderVocabulary Parse(string json, string? source = null)
{
var name = source ?? "lettori";
VocabularyFile? file;
try
{
file = JsonSerializer.Deserialize(json, VocabularyJsonContext.Default.VocabularyFile);
}
catch (JsonException ex)
{
throw new InvalidDataException($"{name}: file non valido (riga {ex.LineNumber + 1}): {ex.Message.Split('.')[0]}.", ex);
}
if (file is null || string.IsNullOrWhiteSpace(file.Site))
{
throw new InvalidDataException($"{name}: manca «site».");
}
var status = file.Status?.Trim().ToLowerInvariant() switch
{
"confermato" or "confirmed" => VocabularyStatus.Confirmed,
"ipotesi" or "hypothesis" or null or "" => VocabularyStatus.Hypothesis,
_ => throw new InvalidDataException($"{name}: stato «{file.Status}» sconosciuto (ammessi: confermato, ipotesi)."),
};
static VocabularyKeys K(List<string>? paths) =>
paths is null ? VocabularyKeys.None : new VocabularyKeys([.. paths.Where(p => !string.IsNullOrWhiteSpace(p)).Select(p => p.Trim())]);
var c = file.Content ?? new ContentDto();
var v = file.Version ?? new VersionDto();
var p = file.Profile ?? new ProfileDto();
var h = file.Highlight ?? new HighlightDto();
var g = file.Page ?? new PageDto();
var s = file.Search ?? new SearchDto();
return new ReaderVocabulary
{
Site = file.Site.Trim(),
Status = status,
Note = file.Note,
Source = source,
Content = new ContentKeys
{
Id = K(c.Id),
Code = K(c.Code),
TakenAt = K(c.TakenAt),
Caption = K(c.Caption),
Images = K(c.Images),
Videos = K(c.Videos),
Children = K(c.Children),
ChildCount = K(c.ChildCount),
Owner = K(c.Owner),
Pinned = K(c.Pinned),
ExpiresAt = K(c.ExpiresAt),
Duration = K(c.Duration),
},
Version = new VersionKeys { Url = K(v.Url), Width = K(v.Width), Height = K(v.Height), HasAudio = K(v.HasAudio) },
Profile = new ProfileKeys
{
Id = K(p.Id),
Username = K(p.Username),
DisplayName = K(p.DisplayName),
IsPrivate = K(p.IsPrivate),
IsFollowed = K(p.IsFollowed),
PostCount = K(p.PostCount),
Picture = K(p.Picture),
LatestStoryAt = K(p.LatestStoryAt),
},
Highlight = new HighlightKeys { Id = K(h.Id), Title = K(h.Title), Owner = K(h.Owner), Items = K(h.Items), Cover = K(h.Cover) },
Page = new PageKeys { HasMore = K(g.HasMore), Cursor = K(g.Cursor) },
Search = new SearchKeys
{
Root = K(s.Root),
Items = K(s.Items),
Position = K(s.Position),
Profile = K(s.Profile),
Id = K(s.Id),
Username = K(s.Username),
DisplayName = K(s.DisplayName),
Picture = K(s.Picture),
Verified = K(s.Verified),
},
Viewer = K(file.Viewer),
Relevance = [.. (file.Relevance?.Keys ?? []).Where(k => !string.IsNullOrWhiteSpace(k)).Select(k => k.Trim()).Distinct(StringComparer.Ordinal)],
};
}
}
internal sealed class VocabularyFile
{
public string? Site { get; set; }
public string? Status { get; set; }
public string? Note { get; set; }
public ContentDto? Content { get; set; }
public VersionDto? Version { get; set; }
public ProfileDto? Profile { get; set; }
public HighlightDto? Highlight { get; set; }
public PageDto? Page { get; set; }
public SearchDto? Search { get; set; }
public List<string>? Viewer { get; set; }
public RelevanceDto? Relevance { get; set; }
}
internal sealed class RelevanceDto
{
public string? Note { get; set; }
public List<string>? Keys { get; set; }
}
internal sealed class ContentDto
{
public string? Note { get; set; }
public List<string>? Id { get; set; }
public List<string>? Code { get; set; }
public List<string>? TakenAt { get; set; }
public List<string>? Caption { get; set; }
public List<string>? Images { get; set; }
public List<string>? Videos { get; set; }
public List<string>? Children { get; set; }
public List<string>? ChildCount { get; set; }
public List<string>? Owner { get; set; }
public List<string>? Pinned { get; set; }
public List<string>? ExpiresAt { get; set; }
public List<string>? Duration { get; set; }
}
internal sealed class VersionDto
{
public string? Note { get; set; }
public List<string>? Url { get; set; }
public List<string>? Width { get; set; }
public List<string>? Height { get; set; }
public List<string>? HasAudio { get; set; }
}
internal sealed class ProfileDto
{
public string? Note { get; set; }
public List<string>? Id { get; set; }
public List<string>? Username { get; set; }
public List<string>? DisplayName { get; set; }
public List<string>? IsPrivate { get; set; }
public List<string>? IsFollowed { get; set; }
public List<string>? PostCount { get; set; }
public List<string>? Picture { get; set; }
public List<string>? LatestStoryAt { get; set; }
}
internal sealed class HighlightDto
{
public string? Note { get; set; }
public List<string>? Id { get; set; }
public List<string>? Title { get; set; }
public List<string>? Owner { get; set; }
public List<string>? Items { get; set; }
public List<string>? Cover { get; set; }
}
internal sealed class PageDto
{
public string? Note { get; set; }
public List<string>? HasMore { get; set; }
public List<string>? Cursor { get; set; }
}
internal sealed class SearchDto
{
public string? Note { get; set; }
public List<string>? Root { get; set; }
public List<string>? Items { get; set; }
public List<string>? Position { get; set; }
public List<string>? Profile { get; set; }
public List<string>? Id { get; set; }
public List<string>? Username { get; set; }
public List<string>? DisplayName { get; set; }
public List<string>? Picture { get; set; }
public List<string>? Verified { get; set; }
}
[JsonSourceGenerationOptions(
PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
ReadCommentHandling = JsonCommentHandling.Skip,
AllowTrailingCommas = true,
UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow)]
[JsonSerializable(typeof(VocabularyFile))]
internal sealed partial class VocabularyJsonContext : JsonSerializerContext;