refactor(core): сужение уровней доступа — internal-нормализаторы, CfbReader и служебные методы валидатора в package-private
PR checks / web (pull_request) Successful in 33s
PR checks / java (pull_request) Successful in 1m16s
Main: tests, deploy, autotests / web (push) Successful in 30s
Main: tests, deploy, autotests / java (push) Successful in 1m18s
Main: tests, deploy, autotests / images-web (push) Successful in 37s
Main: tests, deploy, autotests / images-app (push) Successful in 42s
Main: tests, deploy, autotests / deploy (push) Successful in 1m58s
Main: tests, deploy, autotests / autotests (push) Successful in 40s
Main: tests, deploy, autotests / rollback (push) Has been skipped

- WordPdfValidator: isBinaryDoc/checkPageCount/checkPageCountDoc → package-private
  (наружу остаются checkInput/validate/maxImagePixels)
- CfbReader: класс и readStreams → package-private (все вызывающие в internal/doc)
- 9 STEP-нормализаторов + RubyNormalizer: класс, STEP и normalize → package-private;
  DocxRewritePipeline.normalize → package-private (STEP остаётся публичным)
- javadoc BundledFontMapper: {@link GlyphCoverageNormalizer} → {@code}
- контракты видимости синхронизированы: AGENTS.md, repo-map.md, doc-bridge.md, README.md
This commit was merged in pull request #99.
This commit is contained in:
Pjandro
2026-11-08 20:34:43 +00:00
parent af5d09e001
commit 13ca7425a3
18 changed files with 42 additions and 42 deletions
@@ -98,7 +98,7 @@ public final class WordPdfValidator {
* такой вход не проверяется .docx-валидацией (zip-пути), его страницы
* считает мост {@code internal.doc} по чистому бинарному документу.
*/
public static boolean isBinaryDoc(byte[] bytes) {
static boolean isBinaryDoc(byte[] bytes) {
byte[] sig = {(byte) 0xD0, (byte) 0xCF, 0x11, (byte) 0xE0,
(byte) 0xA1, (byte) 0xB1, 0x1A, (byte) 0xE1};
if (bytes == null || bytes.length < sig.length) {
@@ -147,7 +147,7 @@ public final class WordPdfValidator {
*
* @throws ValidationException при {@code null}, ошибке разбора zip или превышении {@code maxPages}
*/
public static void checkPageCount(byte[] docxBytes, int maxPages) throws ValidationException {
static void checkPageCount(byte[] docxBytes, int maxPages) throws ValidationException {
if (docxBytes == null) {
throw new ValidationException("Не указаны байты входного .docx");
}
@@ -208,7 +208,7 @@ public final class WordPdfValidator {
* @throws ValidationException при {@code null}, не-.doc-входе, шифровании
* или превышении {@code maxPages}
*/
public static void checkPageCountDoc(byte[] docBytes, int maxPages) throws ValidationException {
static void checkPageCountDoc(byte[] docBytes, int maxPages) throws ValidationException {
if (docBytes == null) {
throw new ValidationException("Не указаны байты входного .doc");
}
@@ -107,7 +107,7 @@ public class BundledFontMapper extends BestMatchingMapper {
/**
* Имя шрифта, которое можно поставить в {@code w:rFonts}, чтобы получить
* бандл-семейство {@code family}: {@link GlyphCoverageNormalizer} пишет
* бандл-семейство {@code family}: {@code GlyphCoverageNormalizer} пишет
* его в разрезанные раны. Обратная к {@link #bundledFamily} операция —
* имена берутся из таблицы алиасов, поэтому маппинг гарантированно
* возвращается к тому же семейству.
@@ -24,7 +24,7 @@ import java.util.regex.Pattern;
*
* Если совпадений нет, возвращает исходный массив без переупаковки zip.
*/
public final class DocxOnOffNormalizer {
final class DocxOnOffNormalizer {
/**
* {@code w:val="on"/"off"} только внутри открывающего тега: group 1 — от
@@ -40,7 +40,7 @@ public final class DocxOnOffNormalizer {
}
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = DocxOnOffNormalizer::normalize;
static final DocxNormalizer STEP = DocxOnOffNormalizer::normalize;
/**
* Заменяет в XML-частях docx (word/*.xml) w:val="off"/"on"
@@ -49,7 +49,7 @@ public final class DocxOnOffNormalizer {
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -58,7 +58,7 @@ public final class DocxRewritePipeline {
* @param docx байты .docx (валидный zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
try (ZipFile zf = new ZipFile(new SeekableInMemoryByteChannel(docx));
@@ -36,7 +36,7 @@ import java.util.zip.ZipOutputStream;
* разбираются — если внутри {@code begin … end} встречается ещё один
* {@code begin}, поле пропускается.
*/
public final class FieldNormalizer {
final class FieldNormalizer {
/** Инструкции, для которых в docx4j-export-fo есть обработчик fldSimple. */
private static final String[] SUPPORTED = {"PAGE", "NUMPAGES", "SECTIONPAGES"};
@@ -45,7 +45,7 @@ public final class FieldNormalizer {
}
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = FieldNormalizer::normalize;
static final DocxNormalizer STEP = FieldNormalizer::normalize;
/**
* Переписывает поддерживаемые поля во всех word/*.xml частях docx.
@@ -53,7 +53,7 @@ public final class FieldNormalizer {
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -54,7 +54,7 @@ import java.util.concurrent.ConcurrentHashMap;
*
* Как и {@link SymbolFontNormalizer}, правим байты zip до JAXB-разбора.
*/
public final class GlyphCoverageNormalizer {
final class GlyphCoverageNormalizer {
/** Семейства с засечками: для них fallback ищется сначала среди serif. */
private static final List<String> SERIF_FAMILIES =
@@ -82,7 +82,7 @@ public final class GlyphCoverageNormalizer {
}
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = GlyphCoverageNormalizer::normalize;
static final DocxNormalizer STEP = GlyphCoverageNormalizer::normalize;
/**
* Разрезает раны с непокрытыми глифами в XML-частях docx (word/*.xml).
@@ -90,7 +90,7 @@ public final class GlyphCoverageNormalizer {
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -64,7 +64,7 @@ import org.apache.commons.compress.utils.SeekableInMemoryByteChannel;
*
* <p>Регрессия — WordPdfConverterTest#hiddenText_notPrinted.
*/
public final class HiddenTextNormalizer {
final class HiddenTextNormalizer {
/** Капа цепочки {@code w:basedOn} (образец — {@code doc.Styles.MAX_CHAIN}). */
private static final int MAX_CHAIN = 16;
@@ -98,7 +98,7 @@ public final class HiddenTextNormalizer {
}
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = HiddenTextNormalizer::normalize;
static final DocxNormalizer STEP = HiddenTextNormalizer::normalize;
/**
* Вырезает скрытые раны (только прямой {@code w:vanish}) из XML-частей
@@ -107,7 +107,7 @@ public final class HiddenTextNormalizer {
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
Set<String> vanishStyles = Set.of();
try (ZipFile zf = new ZipFile(new SeekableInMemoryByteChannel(docx))) {
ZipArchiveEntry styles = zf.getEntry("word/styles.xml");
@@ -38,7 +38,7 @@ import java.util.zip.ZipOutputStream;
* Регрессия — WordPdfConverterTest#invisibleChars_noEmptyLines,
* WordPdfConverterTest#invisibleChars_arimoBoxesNotDrawn.
*/
public final class InvisibleCharNormalizer {
final class InvisibleCharNormalizer {
/**
* Коды на вырезание: явные переносы FOP (U+0085, U+2028, U+2029),
@@ -87,7 +87,7 @@ public final class InvisibleCharNormalizer {
}
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = InvisibleCharNormalizer::normalize;
static final DocxNormalizer STEP = InvisibleCharNormalizer::normalize;
/**
* Вырезает невидимые символы из текстовых узлов XML-частей docx
@@ -96,7 +96,7 @@ public final class InvisibleCharNormalizer {
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -29,7 +29,7 @@ import java.util.zip.ZipOutputStream;
* заканчивающийся пробелом lvlText не дублируется. suff=tab/absent/nothing —
* не трогаем. Нечего менять → тот же массив.
*/
public final class NumberingSuffixNormalizer {
final class NumberingSuffixNormalizer {
private static final Pattern SUFF_SPACE =
Pattern.compile("<w:suff\\b[^>]*w:val=\"space\"[^>]*/>");
@@ -39,7 +39,7 @@ public final class NumberingSuffixNormalizer {
}
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = NumberingSuffixNormalizer::normalize;
static final DocxNormalizer STEP = NumberingSuffixNormalizer::normalize;
/**
* Дописывает пробел в lvlText у уровней с suff=space.
@@ -47,7 +47,7 @@ public final class NumberingSuffixNormalizer {
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -33,7 +33,7 @@ import java.util.zip.ZipOutputStream;
*
* <p>Регрессия — WordPdfConverterTest#rubyBase_textPrinted.
*/
public final class RubyNormalizer {
final class RubyNormalizer {
private RubyNormalizer() {
}
@@ -78,7 +78,7 @@ public final class RubyNormalizer {
* Индивидуальный контракт {@link DocxNormalizer} (тесты); в конвейере
* {@link DocxRewritePipeline} вызывает {@link #rewrite} в общем проходе.
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -77,7 +77,7 @@ import java.util.zip.ZipOutputStream;
*
* Регрессия — WordPdfConverterTest#strictOoxml_convertsNotRejected.
*/
public final class StrictOoxmlNormalizer {
final class StrictOoxmlNormalizer {
/** Открывающий тег элемента префикса {@code a:} (DrawingML). */
private static final Pattern A_TAG = Pattern.compile("<a:[A-Za-z]+\\b[^>]*>");
@@ -122,7 +122,7 @@ public final class StrictOoxmlNormalizer {
}
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = StrictOoxmlNormalizer::normalize;
static final DocxNormalizer STEP = StrictOoxmlNormalizer::normalize;
/**
* Приводит strict-OOXML в XML-частях docx (word/*.xml) к виду, который
@@ -131,7 +131,7 @@ public final class StrictOoxmlNormalizer {
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -42,7 +42,7 @@ import java.util.zip.ZipOutputStream;
*
* Как и {@link DocxOnOffNormalizer}, правим байты zip до JAXB-разбора.
*/
public final class SymbolFontNormalizer {
final class SymbolFontNormalizer {
/** Семейство, на которое заменяются символьные шрифты (есть в jar). */
static final String REPLACEMENT_FAMILY = "DejaVu Sans";
@@ -71,7 +71,7 @@ public final class SymbolFontNormalizer {
}
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = SymbolFontNormalizer::normalize;
static final DocxNormalizer STEP = SymbolFontNormalizer::normalize;
/**
* Заменяет символьные шрифты в XML-частях docx (word/*.xml).
@@ -79,7 +79,7 @@ public final class SymbolFontNormalizer {
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -46,7 +46,7 @@ import java.util.zip.ZipOutputStream;
* WordPdfConverterTest#tableIndentCentered_shiftedLikeWord,
* #headerTableIndent_centeredInHeader.
*/
public final class TableIndentNormalizer {
final class TableIndentNormalizer {
/** Дефолт pgSz w:w (A4 portrait, twips) при отсутствии атрибута. */
private static final int DEFAULT_PG_W = 11906;
@@ -75,7 +75,7 @@ public final class TableIndentNormalizer {
}
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = TableIndentNormalizer::normalize;
static final DocxNormalizer STEP = TableIndentNormalizer::normalize;
/**
* Переписывает jc+tblInd в абсолютный tblInd в {@code word/document.xml}.
@@ -83,7 +83,7 @@ public final class TableIndentNormalizer {
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -22,7 +22,7 @@ import java.util.Map;
* любой цепочки ограничена числом секторов файла, иначе враждебный FAT
* зациклил бы разбор.</p>
*/
public final class CfbReader {
final class CfbReader {
/** Сигнатура контейнера, MS-CFB §2.2 (Header Signature). */
static final byte[] SIGNATURE = {(byte) 0xD0, (byte) 0xCF, 0x11, (byte) 0xE0,
@@ -73,7 +73,7 @@ public final class CfbReader {
* @throws ConversionException если это не CFB, файл обрезан или цепочки
* секторов цикличны/указывают за конец файла
*/
public static Map<String, byte[]> readStreams(byte[] cfb) {
static Map<String, byte[]> readStreams(byte[] cfb) {
if (cfb == null || cfb.length < HEADER_SIZE || !startsWithSignature(cfb)) {
throw new ConversionException("Содержимое не похоже на .doc Word 97–2003");
}