@mostajs/file-content-reader 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog — @mostajs/file-content-reader
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com>
+
+## 0.1.0 — 2026-06-10
+- Scaffold (cas C) après livrables DEVRULES **#1 (étude), #2 (audit), #3 (plan)** + script de recherche §8 (`docs/`).
+- Lecture du **contenu texte** d'un fichier (octets → texte), **un lecteur (dialecte) par format** (façon dialects ORM) :
+  `extractText({bytes, filename?, mime?, format?}, {maxChars?})`, `availableFormats()`, `getSupportedFormats()`, `detectFormat()`, `registerReader`/`getReader`.
+  - **`text`** (txt/md/log), **`csv`**, **`html`** (strip-tags) : zéro dépendance (purs).
+  - **`pdf`** (driver `pdf-parse`), **`docx`** (driver `mammoth`) : libs npm **in-memory, lazy** ; `available()` + `installHint` (façon ORM « requires a driver »).
+- **Module fs-free** : reçoit des octets (fournis par `@mostajs/storage`), ne touche pas au disque. **Pendant LECTURE de `@mostajs/file-export`**.
+- Détection de format par extension/mime ; troncature (`maxChars`) pour borner le contexte LLM.
+- Test `test-scripts/run-extract-test.sh` (txt/md/csv/html validés sans dépendance ; pdf/docx selon drivers installés).

package/LICENSE

@@ -0,0 +1,21 @@
+@mostajs/i18n
+Copyright (C) 2026 Dr Hamid MADANI <drmdh@msn.com>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+The complete text of the GNU Affero General Public License version 3 is
+available at the URL above and must accompany any distribution of this
+software.

package/README.md

@@ -0,0 +1,22 @@
+# @mostajs/file-content-reader
+
+Lecture du **contenu texte** d'un fichier (octets → texte) pour les apps `@mostajs/*`, avec **un dialecte
+par format** (façon dialects [`@mostajs/orm`](https://www.npmjs.com/package/@mostajs/orm)) : `txt`, `md`,
+`csv`, `html` (zéro dép) ; `pdf` (`pdf-parse`), `docx` (`mammoth`). **Pendant lecture** de
+[`@mostajs/file-export`](https://www.npmjs.com/package/@mostajs/file-export).
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later
+
+## Principes
+- **fs-free** : reçoit des **octets** (fournis par [`@mostajs/storage`](https://www.npmjs.com/package/@mostajs/storage)) et rend du texte. Ne touche **jamais** au disque.
+- `txt`/`md`/`csv`/`html` : **zéro dépendance**. `pdf`/`docx` : drivers npm **optionnels, lazy** (`pdf-parse`, `mammoth`).
+
+## Usage
+```ts
+import { extractText, availableFormats } from "@mostajs/file-content-reader";
+
+// bytes obtenus via @mostajs/storage (readFileById → stream → Uint8Array)
+const { text, format, truncated } = await extractText({ bytes, filename: "specs.pdf" }, { maxChars: 8000 });
+
+await availableFormats(); // formats réellement lisibles ici (drivers présents)
+```

package/dist/dialects/docx.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Lecteur `docx` — driver `mammoth` (lazy, in-memory ; extractRawText).
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { IContentReader } from "../types.js";
+export declare const docxReader: IContentReader;
+//# sourceMappingURL=docx.d.ts.map

package/dist/dialects/docx.js

@@ -0,0 +1,18 @@
+export const docxReader = {
+    format: "docx", label: "Word (DOCX)", extensions: ["docx"],
+    mimes: ["application/vnd.openxmlformats-officedocument.wordprocessingml.document"],
+    driver: { module: "mammoth", installHint: "npm install mammoth" },
+    async available() { try {
+        await import("mammoth");
+        return true;
+    }
+    catch {
+        return false;
+    } },
+    async extract(bytes) {
+        const mammoth = await import("mammoth");
+        const res = await mammoth.extractRawText({ buffer: Buffer.from(bytes) });
+        return (res.value ?? "").trim();
+    },
+};
+//# sourceMappingURL=docx.js.map

package/dist/dialects/image.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Lecteur `image` — lit le TEXTE d'une image (png/jpg/webp/…) via le fournisseur OCR injecté
+ * (`setOcrProvider`). Sans fournisseur, le format est « indisponible » (dégradation gracieuse).
+ * Le module ne dépend d'aucun moteur : la reconnaissance est déléguée (DI vers @mostajs/ocr).
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { IContentReader } from "../types.js";
+export declare const imageReader: IContentReader;
+//# sourceMappingURL=image.d.ts.map

package/dist/dialects/image.js

@@ -0,0 +1,16 @@
+import { getOcrProvider } from "../ocr.js";
+export const imageReader = {
+    format: "image",
+    label: "Image (OCR)",
+    extensions: ["png", "jpg", "jpeg", "webp", "gif", "bmp", "tif", "tiff"],
+    mimes: ["image/png", "image/jpeg", "image/webp", "image/gif", "image/bmp", "image/tiff"],
+    driver: { module: "@mostajs/ocr", installHint: "setOcrProvider(...) composant @mostajs/ocr" },
+    available() { return !!getOcrProvider(); },
+    async extract(bytes) {
+        const ocr = getOcrProvider();
+        if (!ocr)
+            throw new Error("lecture d'image indisponible : aucun fournisseur OCR injecté (setOcrProvider)");
+        return (await ocr(bytes, { format: "image" }))?.trim() ?? "";
+    },
+};
+//# sourceMappingURL=image.js.map

package/dist/dialects/pdf.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Lecteur `pdf` — driver `pdf-parse` (lazy, in-memory). Compatible v1 (default fonction) ET v2
+ * (classe `PDFParse` + `getText()`). Façon dialect ORM « requires a driver ».
+ *
+ * REPLI OCR : si la couche texte est vide/quasi-vide (PDF scanné, composé d'images) ET qu'un
+ * fournisseur OCR a été injecté (`setOcrProvider`), on lui délègue les octets → texte.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { IContentReader } from "../types.js";
+export declare const pdfReader: IContentReader;
+//# sourceMappingURL=pdf.d.ts.map

package/dist/dialects/pdf.js

@@ -0,0 +1,58 @@
+import { getOcrProvider, OCR_TEXT_THRESHOLD } from "../ocr.js";
+async function extractTextLayer(bytes) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mod = (await import("pdf-parse"));
+    if (typeof mod.default === "function") { // pdf-parse v1
+        const r = await mod.default(Buffer.from(bytes));
+        return String(r?.text ?? "").trim();
+    }
+    const PDFParse = mod.PDFParse ?? mod.default?.PDFParse; // pdf-parse v2
+    if (!PDFParse)
+        throw new Error("API pdf-parse non reconnue");
+    const parser = new PDFParse({ data: bytes });
+    try {
+        const r = await parser.getText();
+        return String(r?.text ?? "").trim();
+    }
+    finally {
+        try {
+            await parser.destroy?.();
+        }
+        catch { /* ignore */ }
+    }
+}
+export const pdfReader = {
+    format: "pdf", label: "PDF", extensions: ["pdf"], mimes: ["application/pdf"],
+    driver: { module: "pdf-parse", installHint: "npm install pdf-parse" },
+    // Disponible si pdf-parse OU un fournisseur OCR est présent (un PDF scanné est lisible par OCR seul).
+    async available() { if (getOcrProvider())
+        return true; try {
+        await import("pdf-parse");
+        return true;
+    }
+    catch {
+        return false;
+    } },
+    async extract(bytes) {
+        // pdf-parse (→ pdfjs) DÉTACHE le buffer d'entrée : on garde une copie intacte pour l'OCR.
+        const ocr = getOcrProvider();
+        const forOcr = ocr ? bytes.slice() : null;
+        let text = "";
+        try {
+            text = await extractTextLayer(bytes);
+        }
+        catch {
+            text = "";
+        }
+        if (text.length >= OCR_TEXT_THRESHOLD)
+            return text;
+        // Couche texte absente/quasi-vide → repli OCR injecté (PDF scanné).
+        if (ocr && forOcr) {
+            const t = (await ocr(forOcr, { format: "pdf" }))?.trim();
+            if (t)
+                return t;
+        }
+        return text;
+    },
+};
+//# sourceMappingURL=pdf.js.map

package/dist/dialects/text.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Lecteurs purs (zéro dépendance) : texte (txt/md/log), csv, html. Author: Dr Hamid MADANI <drmdh@msn.com>
+ * @license AGPL-3.0-or-later
+ */
+import type { IContentReader } from "../types.js";
+export declare const textReader: IContentReader;
+export declare const csvReader: IContentReader;
+export declare const htmlReader: IContentReader;
+//# sourceMappingURL=text.d.ts.map

package/dist/dialects/text.js

@@ -0,0 +1,18 @@
+import { decode, stripHtml } from "../util.js";
+export const textReader = {
+    format: "text", label: "Texte (txt/md)", extensions: ["txt", "md", "markdown", "log", "text"],
+    mimes: ["text/plain", "text/markdown"], driver: null,
+    available() { return true; },
+    async extract(bytes) { return decode(bytes); },
+};
+export const csvReader = {
+    format: "csv", label: "CSV", extensions: ["csv", "tsv"], mimes: ["text/csv", "text/tab-separated-values"], driver: null,
+    available() { return true; },
+    async extract(bytes) { return decode(bytes); },
+};
+export const htmlReader = {
+    format: "html", label: "HTML", extensions: ["html", "htm"], mimes: ["text/html", "application/xhtml+xml"], driver: null,
+    available() { return true; },
+    async extract(bytes) { return stripHtml(decode(bytes)); },
+};
+//# sourceMappingURL=text.js.map

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @mostajs/file-content-reader — point d'entrée. Octets → texte, un lecteur (dialecte) par format.
+ * Importer enregistre les lecteurs built-in (effet de bord). **fs-free** : les octets sont fournis par
+ * le consommateur (typiquement via @mostajs/storage) ; le module ne touche pas au disque.
+ *
+ * Usage : const { text } = await extractText({ bytes, filename: "specs.pdf" }, { maxChars: 8000 });
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { ExtractInput, ExtractResult } from "./types.js";
+import { textReader, csvReader, htmlReader } from "./dialects/text.js";
+import { pdfReader } from "./dialects/pdf.js";
+import { docxReader } from "./dialects/docx.js";
+import { imageReader } from "./dialects/image.js";
+export interface ExtractOptions {
+    maxChars?: number;
+}
+/** Extrait le texte d'un fichier. Détecte le format (format explicite > extension/mime). Tronque à `maxChars`. */
+export declare function extractText(input: ExtractInput, opts?: ExtractOptions): Promise<ExtractResult>;
+/** Formats actuellement lisibles ici (driver présent). */
+export declare function availableFormats(): Promise<string[]>;
+export type { ExtractInput, ExtractResult, IContentReader } from "./types.js";
+export { registerReader, getReader, listReaders, getSupportedFormats, detectFormat } from "./registry.js";
+export { textReader, csvReader, htmlReader, pdfReader, docxReader, imageReader };
+export { setOcrProvider, getOcrProvider, OCR_TEXT_THRESHOLD } from "./ocr.js";
+export type { OcrProvider, OcrContext } from "./ocr.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,41 @@
+import { registerReader, getReader, listReaders, getSupportedFormats, detectFormat } from "./registry.js";
+import { textReader, csvReader, htmlReader } from "./dialects/text.js";
+import { pdfReader } from "./dialects/pdf.js";
+import { docxReader } from "./dialects/docx.js";
+import { imageReader } from "./dialects/image.js";
+registerReader(textReader);
+registerReader(csvReader);
+registerReader(htmlReader);
+registerReader(pdfReader);
+registerReader(docxReader);
+registerReader(imageReader);
+/** Extrait le texte d'un fichier. Détecte le format (format explicite > extension/mime). Tronque à `maxChars`. */
+export async function extractText(input, opts = {}) {
+    const format = input.format || detectFormat(input.filename, input.mime);
+    if (!format)
+        throw new Error(`format non détecté (filename=${input.filename ?? "?"}, mime=${input.mime ?? "?"}) — formats : ${getSupportedFormats().join(", ")}`);
+    const reader = getReader(format);
+    if (!reader)
+        throw new Error(`format « ${format} » non supporté (${getSupportedFormats().join(", ")})`);
+    if (!(await reader.available()))
+        throw new Error(`lecture « ${format} » indisponible : ${reader.driver?.installHint ?? "driver requis"}`);
+    let text = await reader.extract(input.bytes);
+    const max = opts.maxChars ?? 0;
+    const truncated = max > 0 && text.length > max;
+    if (truncated)
+        text = text.slice(0, max) + "\n…[tronqué]";
+    return { text, format, chars: text.length, truncated };
+}
+/** Formats actuellement lisibles ici (driver présent). */
+export async function availableFormats() {
+    const out = [];
+    for (const r of listReaders())
+        if (await r.available())
+            out.push(r.format);
+    return out;
+}
+export { registerReader, getReader, listReaders, getSupportedFormats, detectFormat } from "./registry.js";
+export { textReader, csvReader, htmlReader, pdfReader, docxReader, imageReader };
+// OCR injectable (DI) — le consommateur compose @mostajs/image + @mostajs/ocr.
+export { setOcrProvider, getOcrProvider, OCR_TEXT_THRESHOLD } from "./ocr.js";
+//# sourceMappingURL=index.js.map

package/dist/ocr.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @mostajs/file-content-reader — fournisseur OCR INJECTABLE (DI). Le module reste générique : il
+ * ne dépend NI de @mostajs/image NI de @mostajs/ocr. Le consommateur (racine de composition)
+ * injecte une fonction qui sait transformer des octets (PDF scanné, image) en texte — typiquement
+ * en composant `@mostajs/image` (rendu des pages) + `@mostajs/ocr` (reconnaissance).
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+/** Contexte passé au fournisseur OCR. */
+export interface OcrContext {
+    format: string;
+    filename?: string;
+    mime?: string;
+}
+/** Fournisseur OCR : octets → texte (ou null si rien). */
+export type OcrProvider = (bytes: Uint8Array, ctx: OcrContext) => Promise<string | null>;
+/** Injecte (ou retire avec null) le fournisseur OCR global. */
+export declare function setOcrProvider(fn: OcrProvider | null): void;
+/** Fournisseur OCR courant (ou null). */
+export declare function getOcrProvider(): OcrProvider | null;
+/** Seuil sous lequel un PDF est considéré « sans couche texte » (scanné) → bascule OCR. */
+export declare const OCR_TEXT_THRESHOLD = 16;
+//# sourceMappingURL=ocr.d.ts.map

package/dist/ocr.js

@@ -0,0 +1,16 @@
+/**
+ * @mostajs/file-content-reader — fournisseur OCR INJECTABLE (DI). Le module reste générique : il
+ * ne dépend NI de @mostajs/image NI de @mostajs/ocr. Le consommateur (racine de composition)
+ * injecte une fonction qui sait transformer des octets (PDF scanné, image) en texte — typiquement
+ * en composant `@mostajs/image` (rendu des pages) + `@mostajs/ocr` (reconnaissance).
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+let _provider = null;
+/** Injecte (ou retire avec null) le fournisseur OCR global. */
+export function setOcrProvider(fn) { _provider = fn; }
+/** Fournisseur OCR courant (ou null). */
+export function getOcrProvider() { return _provider; }
+/** Seuil sous lequel un PDF est considéré « sans couche texte » (scanné) → bascule OCR. */
+export const OCR_TEXT_THRESHOLD = 16;
+//# sourceMappingURL=ocr.js.map

package/dist/registry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @mostajs/file-content-reader — registre de lecteurs (dialectes) + détection de format.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { IContentReader } from "./types.js";
+export declare function registerReader(r: IContentReader): void;
+export declare function getReader(format: string): IContentReader | null;
+export declare function listReaders(): IContentReader[];
+export declare function getSupportedFormats(): string[];
+/** Détecte le format depuis un nom de fichier (extension) ou un type MIME. */
+export declare function detectFormat(filename?: string, mime?: string): string | null;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.js

@@ -0,0 +1,18 @@
+const READERS = new Map();
+export function registerReader(r) { READERS.set(r.format, r); }
+export function getReader(format) { return READERS.get(format) ?? null; }
+export function listReaders() { return Array.from(READERS.values()); }
+export function getSupportedFormats() { return Array.from(READERS.keys()); }
+/** Détecte le format depuis un nom de fichier (extension) ou un type MIME. */
+export function detectFormat(filename, mime) {
+    const ext = (filename ?? "").toLowerCase().split(".").pop() ?? "";
+    const m = (mime ?? "").toLowerCase().split(";")[0].trim();
+    for (const r of READERS.values()) {
+        if (ext && r.extensions.includes(ext))
+            return r.format;
+        if (m && r.mimes.includes(m))
+            return r.format;
+    }
+    return null;
+}
+//# sourceMappingURL=registry.js.map

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @mostajs/file-content-reader — types. Lecture du contenu texte d'un fichier (octets → texte),
+ * un **dialecte par format** (façon dialects ORM). Pendant LECTURE de @mostajs/file-export.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+/** Entrée : octets (fournis par @mostajs/storage) + indices de format (nom/mime/format explicite). */
+export interface ExtractInput {
+    bytes: Uint8Array;
+    filename?: string;
+    mime?: string;
+    format?: string;
+}
+/** Résultat : texte extrait + format détecté + métriques. */
+export interface ExtractResult {
+    text: string;
+    format: string;
+    chars: number;
+    truncated: boolean;
+}
+/**
+ * **Lecteur de contenu** (dialecte) — porte ses extensions/mimes (détection), son driver
+ * (`{module, installHint}` + `available()`) et `extract(bytes) → texte`. fs-free.
+ */
+export interface IContentReader {
+    readonly format: string;
+    readonly label: string;
+    readonly extensions: string[];
+    readonly mimes: string[];
+    readonly driver?: {
+        module: string;
+        installHint: string;
+    } | null;
+    available(): boolean | Promise<boolean>;
+    extract(bytes: Uint8Array): Promise<string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * @mostajs/file-content-reader — types. Lecture du contenu texte d'un fichier (octets → texte),
+ * un **dialecte par format** (façon dialects ORM). Pendant LECTURE de @mostajs/file-export.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/util.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @mostajs/file-content-reader — utilitaires partagés.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+export declare const decode: (bytes: Uint8Array) => string;
+/** HTML → texte : retire scripts/styles + balises, décode quelques entités, normalise les blancs. */
+export declare function stripHtml(html: string): string;
+//# sourceMappingURL=util.d.ts.map

package/dist/util.js

@@ -0,0 +1,15 @@
+/**
+ * @mostajs/file-content-reader — utilitaires partagés.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+export const decode = (bytes) => new TextDecoder("utf-8").decode(bytes);
+/** HTML → texte : retire scripts/styles + balises, décode quelques entités, normalise les blancs. */
+export function stripHtml(html) {
+    return html
+        .replace(/<(script|style)[\s\S]*?<\/\1>/gi, " ")
+        .replace(/<\/(p|div|li|tr|h[1-6]|br)>/gi, "\n")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&nbsp;/gi, " ").replace(/&amp;/gi, "&").replace(/&lt;/gi, "<").replace(/&gt;/gi, ">").replace(/&quot;/gi, '"')
+        .replace(/[ \t]+/g, " ").replace(/\n{3,}/g, "\n\n").trim();
+}
+//# sourceMappingURL=util.js.map

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@mostajs/file-content-reader",
+  "version": "0.1.0",
+  "description": "Lecture du CONTENU texte d'un fichier (octets → texte) pour apps @mostajs/* — un dialecte par format (façon dialects @mostajs/orm) : txt, md, csv, html (zéro dép) ; pdf (pdf-parse), docx (mammoth) via drivers optionnels lazy. fs-free : reçoit des octets (fournis par @mostajs/storage), ne touche pas au disque. Pendant LECTURE de @mostajs/file-export.",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "pdf-parse": ">=1.1.0",
+    "mammoth": ">=1.6.0"
+  },
+  "peerDependenciesMeta": {
+    "pdf-parse": {
+      "optional": true
+    },
+    "mammoth": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  },
+  "keywords": [
+    "file",
+    "content",
+    "reader",
+    "extract",
+    "text",
+    "pdf",
+    "docx",
+    "ocr",
+    "dialect",
+    "mostajs"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}