README

fstats — statistiques de fichiers texte en ligne de commande

Version 2.7.0 · Free Pascal (mode objfpc) · MIT

fstats est un petit outil, rapide et sans dépendances, qui analyse des fichiers texte UTF-8 et affiche des statistiques : caractères, mots, lignes, phrases, mots les plus fréquents, n-grammes, histogrammes… Il peut aussi servir de garde-fou en CI : checks sur des seuils (--fail-if), comparaison à une baseline (--compare) et exit codes dédiés (0/1/2/3).

Il tourne sur Windows et Linux, seul, sans environnement lourd : il suffit du compilateur Free Pascal pour le construire.

👋 Nouveau ici ? Commence par le guide pédagogique : il explique pas à pas, sans jargon, ce que fait l'outil et comment l'utiliser.

Démarrage rapide

Compilation depuis la racine du dépôt :

fpc -O2 -Mobjfpc -FE. src\fstats.pas

L'exécutable fstats.exe est créé à la racine (wbld.bat fait pareil sous Windows ; wclr.bat nettoie les artefacts de compilation).

Premières analyses :

fstats mon-fichier.txt          # statistiques compl??tes ?? l'écran
fstats "**/*.md"                # tous les .md du dossier (glob interne)
echo "un deux trois." | fstats - --summary-json   # depuis l'entr??e standard
fstats --json mon-fichier.txt   # export JSON

Ce que fstats sait faire

Utilisation

fstats [options] <fichier|glob|-> [fichier2 ...]

Entrées

Analyse du texte

Checks et comparaison (CI)

Métriques du gate : lines, words, sentences, max_line_length, avg_words_per_sentence (alias avg_sentence_words), non_utf8 (alias invalid_utf8), bom, crlf, tabs, nonprintable. Opérateurs : >, >=, <, <=, =, !=. (Sous CMD, échapper > : --fail-if lines^>5 ou --fail-if "lines>5".)

Affichage et export

Exemples

fstats examples\demo.obm
fstats --json --out=stats.json examples\demo.obm
fstats --csv=words --all rapport.txt
fstats --recursive=docs --include='**/*.md' --summary-json
echo "un deux trois." | fstats - --json
fstats 'tests/**/*.md' --json-mode=aggregate
fstats --word-mode=ascii --top-words=20 --lexical-stats corpus.txt
fstats --sentence-mode=smart rapport.txt
fstats --sentence-mode=smart --check --fail-if avg_words_per_sentence>25 docs/*.md
fstats --casefold=unicode --lexical-stats --json corpus_fr.txt
fstats --ngrams=3 --top-ngrams=20 --word-mode=ascii corpus.txt
fstats --ngrams=2 --stopwords=fr corpus_fr.txt
fstats --histogram=line_length --histogram=word_length rapport.txt
fstats --char-classes --json corpus.txt
fstats --readability rapport.txt
fstats --readability --word-mode=ascii --summary-json corpus.txt
fstats docs/**/*.md --check --fail-if max_line_length>120 --fail-if non_utf8>0
fstats app.log - --check --fail-if max_line_length>500       # via stdin
fstats --summary-json docs/*.md > baseline.ndjson            # capture
fstats docs/*.md --compare baseline.ndjson --fail-on-delta lines>10
fstats --help

Formats de sortie

• Console : sections alignées en ASCII pur (Summary, Checks, Quality, Lexical, Readability, Top Characters/Words, Longest Lines, N-grams, Histogram, Character Classes), sans séquence ANSI — sûre pour les scripts et pipes.
• JSON : champs de traçabilité (tool, version, schema_version, generated) + statistics, quality, et blocs additifs (checks, lexical, readability, ngrams, histogram, char_classes) selon les options.
• CSV v2 : en-tête fixe file,type,rank,value,code_point,count,length, trois sous-formats (summary, words, chars).

Les détails précis (exemples complets, schémas JSON, ruptures documentées) sont dans la spécification technique.

Codes de retour

Les données vont sur stdout ; les erreurs, avertissements et confirmations --out vont sur stderr.

Documentation

Tests automatisés

• tests\run.bat (Windows / CMD) et tests\run.sh (Linux / Git Bash) : compilation + 59 cas d'acceptation (Cible 1 A/B/C, Cible 2 A/B/C) avec validation JSON via node et vérification des codes de retour.
• Prérequis : fpc et node sur le PATH.
• La CI GitHub Actions exécute les deux suites sur windows-latest et ubuntu-latest à chaque push sur main et chaque pull_request.

Structure du projet

fstats/
????????? .github/workflows/ci.yml  # CI GitHub Actions (Windows + Linux)
????????? doc/                      # Documentation (guide, spec, roadmaps, validation)
????????? examples/demo.obm         # Fichier de d??monstration
????????? src/fstats.pas            # Code source unique (Free Pascal)
????????? tests/                    # Suites de tests + fixtures
????????? LICENSE                   # Licence MIT
????????? README.md

Limites connues (en bref)

• Fichiers texte UTF-8 uniquement : une séquence invalide est remplacée par U+FFFD et comptée (invalid_utf8).
• Le BOM est détecté mais conservé (choix assumé).
• La définition par défaut d'un mot inclut la ponctuation attachée (mode raw) ; --word-mode=ascii|unicode retire la ponctuation.
• Le case folding unicode est une table basique limitée (accents français/allemand), pas un folding Unicode complet.
• N-grammes : top-K approximatif sur très gros corpus (sketch mémoire borné) ; non agrégés en --json-mode=aggregate.
• Un point entre deux chiffres (3.14) ne clôture pas une phrase (v2.6.1) ; un point après un chiffre suivi d'un espace (Version 3.) reste une fin de phrase.
• Le score de lisibilité (--readability) est une approximation sans syllabes : ce n'est pas un Flesch-Kincaid exact (la formule est figée dans la spécification technique).

Toutes les sémantiques sont détaillées et figées dans la spécification technique.