@gabrielerandelli/minus-tracker 0.6.0 → 0.8.0

package/dist/index.cjs

@@ -152,6 +152,10 @@ function warningToEnglish(w) {
       return `Row ${w.row}: no ECB rate for ${w.currency} on ${w.date} \u2014 skipped`;
     case "QUANTITY_ZERO":
       return `Row ${w.row}: quantity is 0 \u2014 skipped`;
+    case "MISSING_ISIN_INCOME":
+      return `Row ${w.row}: blank ISIN on income row \u2014 skipped`;
+    case "ORPHAN_WITHHOLDING":
+      return `Withholding row for ${w.isin} on ${w.date}: no matching income row \u2014 skipped`;
   }
 }
 
@@ -167,6 +171,8 @@ var REQUIRED_COLUMNS = [
   "Transaction costs currency",
   "Product"
 ];
+var INCOME_KEYWORDS = ["DIVIDEND", "COUPON", "INTEREST", "CEDOLA"];
+var TAX_KEYWORDS = ["DIVIDEND TAX", "WITHHOLDING", "RITENUTA"];
 function parseCSVRow(line) {
   const fields = [];
   let i = 0;
@@ -208,6 +214,7 @@ function parseDate(ddmmyyyy) {
 var DEGIROParser = class {
   _warningEntries = [];
   _snapshot;
+  _incomeRows = [];
   constructor(snapshot) {
     this._snapshot = snapshot;
   }
@@ -224,6 +231,7 @@ var DEGIROParser = class {
    */
   parse(csv) {
     this._warningEntries = [];
+    this._incomeRows = [];
     if (typeof csv !== "string" || csv.includes("\0")) {
       throw new ParseError("INVALID_CSV");
     }
@@ -248,17 +256,70 @@ var DEGIROParser = class {
     }
     const snapshot = this._snapshot ?? getActiveSnapshot();
     const transactions = [];
+    const incomeCandidates = [];
+    const withholdingCandidates = [];
     for (let r = 1; r < rows.length; r++) {
       const row = rows[r];
       const rowIndex = r + 1;
       if (row.every((cell) => cell.trim() === "")) continue;
       const get = (col) => (row[colIndex[col]] ?? "").trim();
       const isin = get("ISIN");
+      const product = get("Product");
+      const qtyStr = get("Quantity");
+      const rawQty = parseFloat(qtyStr);
+      const qtyIsZeroOrBlank = qtyStr === "" || isNaN(rawQty) || rawQty === 0;
+      if (qtyIsZeroOrBlank) {
+        const upperProduct = product.toUpperCase();
+        const isTaxKeyword = TAX_KEYWORDS.some((k) => upperProduct.includes(k));
+        const isIncomeKeyword = !isTaxKeyword && INCOME_KEYWORDS.some((k) => upperProduct.includes(k));
+        if (isTaxKeyword || isIncomeKeyword) {
+          const rawLocalValue = parseFloat(get("Local value"));
+          const localValue = isNaN(rawLocalValue) ? 0 : rawLocalValue;
+          const isoDate2 = parseDate(get("Date"));
+          if (isTaxKeyword && localValue < 0) {
+            if (!isin) {
+              this._warningEntries.push({
+                code: "MISSING_ISIN_INCOME",
+                row: rowIndex
+              });
+              continue;
+            }
+            withholdingCandidates.push({
+              isin,
+              date: isoDate2,
+              amount: Math.abs(localValue),
+              row: rowIndex
+            });
+            continue;
+          }
+          if (isIncomeKeyword && localValue > 0) {
+            if (!isin) {
+              this._warningEntries.push({
+                code: "MISSING_ISIN_INCOME",
+                row: rowIndex
+              });
+              continue;
+            }
+            const incomeType = upperProduct.includes(
+              "DIVIDEND"
+            ) ? "dividend" : "coupon";
+            incomeCandidates.push({
+              isin,
+              product,
+              date: isoDate2,
+              incomeType,
+              localValue,
+              currency: get("Local value currency"),
+              row: rowIndex
+            });
+            continue;
+          }
+        }
+      }
       if (!isin) {
         this._warningEntries.push({ code: "MISSING_ISIN", row: rowIndex });
         continue;
       }
-      const rawQty = parseFloat(get("Quantity"));
       if (isNaN(rawQty) || rawQty === 0) {
         this._warningEntries.push({ code: "QUANTITY_ZERO", row: rowIndex });
         continue;
@@ -299,7 +360,6 @@ var DEGIROParser = class {
       const rawFees = parseFloat(get("Transaction costs"));
       const feesEUR = Math.abs(isNaN(rawFees) ? 0 : rawFees);
       const pricePerUnit = parseFloat(get("Price"));
-      const product = get("Product");
       transactions.push({
         isin,
         product,
@@ -314,6 +374,73 @@ var DEGIROParser = class {
         fxRate
       });
     }
+    const withholdingByKey = /* @__PURE__ */ new Map();
+    for (const w of withholdingCandidates) {
+      const key = `${w.isin}|${w.date}`;
+      const existing = withholdingByKey.get(key);
+      withholdingByKey.set(key, {
+        isin: w.isin,
+        date: w.date,
+        amount: (existing?.amount ?? 0) + w.amount
+      });
+    }
+    const consumedKeys = /* @__PURE__ */ new Set();
+    const incomeRows = [];
+    for (const c of incomeCandidates) {
+      const key = `${c.isin}|${c.date}`;
+      const matchedWithholding = withholdingByKey.get(key);
+      let grossAmount;
+      let withholdingTax;
+      let fxRate;
+      if (c.currency === "EUR") {
+        grossAmount = Math.abs(c.localValue);
+        withholdingTax = matchedWithholding?.amount ?? 0;
+        fxRate = void 0;
+      } else {
+        const rate = lookupRate(c.currency, c.date, snapshot);
+        if (rate === null) {
+          if (snapshot[c.currency] === void 0) {
+            this._warningEntries.push({
+              code: "UNSUPPORTED_CURRENCY",
+              row: c.row,
+              currency: c.currency
+            });
+          } else {
+            this._warningEntries.push({
+              code: "NO_ECB_RATE",
+              row: c.row,
+              currency: c.currency,
+              date: c.date
+            });
+          }
+          continue;
+        }
+        grossAmount = Math.abs(c.localValue) / rate;
+        withholdingTax = matchedWithholding ? matchedWithholding.amount / rate : 0;
+        fxRate = rate;
+      }
+      if (matchedWithholding) consumedKeys.add(key);
+      incomeRows.push({
+        isin: c.isin,
+        product: c.product,
+        date: c.date,
+        incomeType: c.incomeType,
+        grossAmount,
+        withholdingTax,
+        currency: c.currency,
+        fxRate
+      });
+    }
+    for (const [key, w] of withholdingByKey) {
+      if (!consumedKeys.has(key)) {
+        this._warningEntries.push({
+          code: "ORPHAN_WITHHOLDING",
+          isin: w.isin,
+          date: w.date
+        });
+      }
+    }
+    this._incomeRows = incomeRows;
     return transactions;
   }
   get warnings() {
@@ -322,12 +449,136 @@ var DEGIROParser = class {
   get warningEntries() {
     return this._warningEntries;
   }
+  get incomeRows() {
+    return this._incomeRows;
+  }
 };
 
-// src/calculator/index.ts
+// src/dichiarazione/engine.ts
+var import_promises = require("fs/promises");
 function roundHalfUp(x) {
   return Math.sign(x) * Math.round(Math.abs(x) * 100) / 100;
 }
+function buildQuadroRT(bucketB, carryForward, taxYear) {
+  const plusvalenze = bucketB.plusvalenze;
+  const minusvalenze = bucketB.minusvalenze;
+  const differenza = roundHalfUp(plusvalenze - minusvalenze);
+  if (differenza > 0) {
+    const sorted = [...carryForward].sort((a, b) => a.year - b.year);
+    let remaining = differenza;
+    const carryForwardApplied = [];
+    for (const entry of sorted) {
+      if (taxYear - entry.year > 4) continue;
+      const consumed = Math.min(entry.amount, remaining);
+      if (consumed > 0) {
+        carryForwardApplied.push({
+          annoOrigine: entry.year,
+          importo: roundHalfUp(consumed)
+        });
+        remaining -= consumed;
+      }
+    }
+    const imponibileNetto = roundHalfUp(remaining);
+    const imposta = roundHalfUp(imponibileNetto * 0.26);
+    return {
+      plusvalenze,
+      minusvalenze,
+      differenza,
+      carryForwardApplied,
+      imponibileNetto,
+      imposta,
+      carryForwardRiportato: []
+    };
+  } else if (differenza < 0) {
+    return {
+      plusvalenze,
+      minusvalenze,
+      differenza,
+      carryForwardApplied: [],
+      imponibileNetto: 0,
+      imposta: 0,
+      carryForwardRiportato: [
+        { annoOrigine: taxYear, importo: roundHalfUp(Math.abs(differenza)) }
+      ]
+    };
+  } else {
+    return {
+      plusvalenze,
+      minusvalenze,
+      differenza: 0,
+      carryForwardApplied: [],
+      imponibileNetto: 0,
+      imposta: 0,
+      carryForwardRiportato: []
+    };
+  }
+}
+function buildQuadroRM(bucketA, incomeRows, taxYear) {
+  const groups = bucketA?.groups ?? [];
+  const group26 = groups.find((g) => g.taxRate === 0.26);
+  const group125 = groups.find((g) => g.taxRate === 0.125);
+  const capitaleAliquota26 = {
+    plusvalenze: group26?.plusvalenze ?? 0,
+    imposta: group26?.imposta ?? 0
+  };
+  const capitaleAliquota125 = {
+    plusvalenze: group125?.plusvalenze ?? 0,
+    imposta: group125?.imposta ?? 0
+  };
+  const dividendiEsteri = incomeRows.filter((r) => r.incomeType === "dividend").map((r) => ({
+    isin: r.isin,
+    prodotto: r.product,
+    lordo: r.grossAmount,
+    rittenutaEstera: r.withholdingTax
+  }));
+  const cedole = incomeRows.filter((r) => r.incomeType === "coupon").map((r) => ({
+    isin: r.isin,
+    prodotto: r.product,
+    importo: r.grossAmount,
+    rittenutaEstera: r.withholdingTax
+  }));
+  return {
+    capitaleAliquota26,
+    capitaleAliquota125,
+    dividendiEsteri,
+    cedole
+  };
+}
+function buildDichiarazioneReport(quadroRT, quadroRM, taxYear) {
+  const version = 1;
+  const modello = "Redditi PF";
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    version,
+    annoImposta: taxYear,
+    modello,
+    generatedAt,
+    quadroRT,
+    quadroRM,
+    exportTo: async (path2) => {
+      await (0, import_promises.writeFile)(
+        path2,
+        JSON.stringify(
+          {
+            version,
+            annoImposta: taxYear,
+            modello,
+            generatedAt,
+            quadroRT,
+            quadroRM
+          },
+          null,
+          2
+        )
+      );
+    }
+  };
+}
+
+// src/calculator/index.ts
+function roundHalfUp2(x) {
+  return Math.sign(x) * Math.round(Math.abs(x) * 100) / 100;
+}
 function inferTaxYear(transactions) {
   const counts = {};
   for (const t of transactions) {
@@ -419,9 +670,9 @@ var Calculator = class {
             sellDate: tx.date,
             buyPriceEUR: lot.pricePerUnitEUR,
             sellPriceEUR: sellPricePerUnitEUR,
-            buyCostEUR: roundHalfUp(buyCostEUR),
-            sellProceedsEUR: roundHalfUp(sellProceedsEUR),
-            gainLossEUR: roundHalfUp(gainLossEUR),
+            buyCostEUR: roundHalfUp2(buyCostEUR),
+            sellProceedsEUR: roundHalfUp2(sellProceedsEUR),
+            gainLossEUR: roundHalfUp2(gainLossEUR),
             buyFxRate: lot.fxRate,
             sellFxRate: tx.fxRate
           });
@@ -476,12 +727,12 @@ var Calculator = class {
       const bucketAGroups = [...groupsByRate.entries()].map(([taxRate, g]) => ({
         taxRate,
         assetClasses: [...g.assetClasses],
-        plusvalenze: roundHalfUp(g.plusvalenze),
-        imposta: roundHalfUp(g.plusvalenze * taxRate)
+        plusvalenze: roundHalfUp2(g.plusvalenze),
+        imposta: roundHalfUp2(g.plusvalenze * taxRate)
       }));
       const bucketAReport = {
         groups: bucketAGroups,
-        totalImposta: roundHalfUp(
+        totalImposta: roundHalfUp2(
           bucketAGroups.reduce((s, g) => s + g.imposta, 0)
         )
       };
@@ -492,8 +743,8 @@ var Calculator = class {
         if (lot.gainLossEUR >= 0) bPlusvalenze += lot.gainLossEUR;
         else bMinusvalenze += Math.abs(lot.gainLossEUR);
       }
-      bPlusvalenze = roundHalfUp(bPlusvalenze);
-      bMinusvalenze = roundHalfUp(bMinusvalenze);
+      bPlusvalenze = roundHalfUp2(bPlusvalenze);
+      bMinusvalenze = roundHalfUp2(bMinusvalenze);
       const carryForwards = [...this._options.carryForward ?? []].sort(
         (a, b) => a.year - b.year
       );
@@ -506,11 +757,11 @@ var Calculator = class {
         carryForwardApplied += consumed;
         remaining -= consumed;
       }
-      carryForwardApplied = roundHalfUp(carryForwardApplied);
-      const bNetResult = roundHalfUp(
+      carryForwardApplied = roundHalfUp2(carryForwardApplied);
+      const bNetResult = roundHalfUp2(
         bPlusvalenze - bMinusvalenze - carryForwardApplied
       );
-      const carryForwardRemaining = roundHalfUp(Math.max(0, -bNetResult));
+      const carryForwardRemaining = roundHalfUp2(Math.max(0, -bNetResult));
       const bucketBReport = {
         plusvalenze: bPlusvalenze,
         minusvalenze: bMinusvalenze,
@@ -518,18 +769,41 @@ var Calculator = class {
         carryForwardRemaining,
         netResult: bNetResult
       };
+      const allIncomeRows = this._options.incomeRows ?? [];
+      const filteredIncomeRows = allIncomeRows.filter(
+        (row) => new Date(row.date).getFullYear() === taxYear
+      );
+      if (filteredIncomeRows.length < allIncomeRows.length) {
+        warnings.push(`Income rows outside tax year ${taxYear} were skipped.`);
+      }
+      const quadroRT = buildQuadroRT(
+        bucketBReport,
+        this._options.carryForward ?? [],
+        taxYear
+      );
+      const quadroRM = buildQuadroRM(
+        bucketAGroups.length > 0 ? bucketAReport : void 0,
+        filteredIncomeRows,
+        taxYear
+      );
+      const dichiarazioneReport = buildDichiarazioneReport(
+        quadroRT,
+        quadroRM,
+        taxYear
+      );
       return {
         method,
         taxYear,
-        plusvalenze: roundHalfUp(plusvalenze),
-        minusvalenze: roundHalfUp(minusvalenze),
-        netResult: roundHalfUp(plusvalenze - minusvalenze),
+        plusvalenze: roundHalfUp2(plusvalenze),
+        minusvalenze: roundHalfUp2(minusvalenze),
+        netResult: roundHalfUp2(plusvalenze - minusvalenze),
         lots: matchedLots,
         ratesUsed,
         warnings,
         generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
         bucketA: bucketAGroups.length > 0 ? bucketAReport : void 0,
-        bucketB: bucketBReport
+        bucketB: bucketBReport,
+        dichiarazione: dichiarazioneReport
       };
     } else {
       const allIsins = [...new Set(this._transactions.map((t) => t.isin))];
@@ -544,9 +818,9 @@ var Calculator = class {
     return {
       method,
       taxYear,
-      plusvalenze: roundHalfUp(plusvalenze),
-      minusvalenze: roundHalfUp(minusvalenze),
-      netResult: roundHalfUp(plusvalenze - minusvalenze),
+      plusvalenze: roundHalfUp2(plusvalenze),
+      minusvalenze: roundHalfUp2(minusvalenze),
+      netResult: roundHalfUp2(plusvalenze - minusvalenze),
       lots: matchedLots,
       ratesUsed,
       warnings,
@@ -768,7 +1042,7 @@ function classifyByType(isin, securityType, product, warnings) {
     };
   }
   warnings.push(
-    `Unrecognized type: ${securityType}. Please classify manually.`
+    `Unrecognized type for ${isin}: ${securityType}. Please classify manually.`
   );
   return {
     product,
@@ -781,6 +1055,84 @@ function classifyByType(isin, securityType, product, warnings) {
     source: "user"
   };
 }
+var ASSET_CLASS_DEFAULTS = {
+  ETF: {
+    assetClass: "ETF",
+    bucketGain: "A",
+    bucketLoss: "B",
+    taxRate: 0.26,
+    whiteListed: null
+  },
+  Stock: {
+    assetClass: "Stock",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  ETC: {
+    assetClass: "ETC",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  GovtBondWL: {
+    assetClass: "GovtBondWL",
+    bucketGain: "A",
+    bucketLoss: "B",
+    taxRate: 0.125,
+    whiteListed: true
+  },
+  GovtBondOther: {
+    assetClass: "GovtBondOther",
+    bucketGain: "A",
+    bucketLoss: "B",
+    taxRate: 0.26,
+    whiteListed: false
+  },
+  CorpBond: {
+    assetClass: "CorpBond",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  Derivative: {
+    assetClass: "Derivative",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  LeverageCert: {
+    assetClass: "LeverageCert",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  CapProtectedCert: {
+    assetClass: "CapProtectedCert",
+    bucketGain: "A",
+    bucketLoss: "B",
+    taxRate: 0.26,
+    whiteListed: null
+  }
+};
+function buildEntryFromAssetClass(assetClass, product) {
+  const mapped = ASSET_CLASS_DEFAULTS[assetClass];
+  return {
+    product,
+    assetClass: mapped.assetClass,
+    bucketGain: mapped.bucketGain,
+    bucketLoss: mapped.bucketLoss,
+    taxRate: mapped.taxRate,
+    whiteListed: mapped.whiteListed,
+    confirmedByUser: true,
+    source: "user"
+  };
+}
 var Classifier = class {
   interactive;
   constructor(options) {
@@ -802,7 +1154,7 @@ var Classifier = class {
     }
     return parsed.classifications;
   }
-  async classify(transactions, sidecarPath, _httpPost = httpsPost) {
+  async classify(transactions, sidecarPath, options, _httpPost = httpsPost) {
     const isinToProduct = /* @__PURE__ */ new Map();
     for (const tx of transactions) {
       if (tx.isin && !isinToProduct.has(tx.isin)) {
@@ -810,13 +1162,21 @@ var Classifier = class {
       }
     }
     const confirmed = {};
-    if (fs2.existsSync(sidecarPath)) {
-      const existingMap = await this.load(sidecarPath);
-      for (const [isin, entry] of Object.entries(existingMap)) {
-        if (entry.confirmedByUser) {
-          confirmed[isin] = entry;
+    if (sidecarPath !== void 0) {
+      if (fs2.existsSync(sidecarPath)) {
+        const existingMap = await this.load(sidecarPath);
+        for (const [isin, entry] of Object.entries(existingMap)) {
+          if (entry.confirmedByUser) {
+            confirmed[isin] = entry;
+          }
         }
       }
+    } else if (options?.existingClassification) {
+      Object.assign(confirmed, options.existingClassification);
+    }
+    for (const [isin, assetClass] of Object.entries(options?.overrides ?? {})) {
+      const product = isinToProduct.get(isin) ?? isin;
+      confirmed[isin] = buildEntryFromAssetClass(assetClass, product);
     }
     const toProcess = [];
     for (const isin of isinToProduct.keys()) {
@@ -826,76 +1186,100 @@ var Classifier = class {
     }
     const warnings = [];
     const newEntries = {};
-    const BATCH_SIZE = 10;
-    for (let i = 0; i < toProcess.length; i += BATCH_SIZE) {
-      if (i > 0) {
-        await new Promise((resolve) => setTimeout(resolve, 6e3));
+    if (options?.offline) {
+      for (const isin of toProcess) {
+        const product = isinToProduct.get(isin) ?? isin;
+        warnings.push(
+          `Unrecognized type for ${isin}: unknown. Please classify manually.`
+        );
+        newEntries[isin] = {
+          product,
+          assetClass: "Stock",
+          bucketGain: "B",
+          bucketLoss: "B",
+          taxRate: 0,
+          whiteListed: null,
+          confirmedByUser: false,
+          source: "user"
+        };
       }
-      const batch = toProcess.slice(i, i + BATCH_SIZE);
-      const requestBody = JSON.stringify(
-        batch.map((isin) => ({ idType: "ID_ISIN", idValue: isin }))
-      );
-      let response = null;
-      for (let attempt = 0; attempt < 2; attempt++) {
-        try {
-          const r = await _httpPost(
-            "https://api.openfigi.com/v3/mapping",
-            requestBody,
-            1e4
-          );
-          if (r.status < 500) {
-            response = r;
-            break;
+    } else {
+      const BATCH_SIZE = 10;
+      const totalBatches = Math.ceil(toProcess.length / BATCH_SIZE);
+      for (let i = 0; i < toProcess.length; i += BATCH_SIZE) {
+        if (i > 0) {
+          await new Promise((resolve) => setTimeout(resolve, 6e3));
+        }
+        const batch = toProcess.slice(i, i + BATCH_SIZE);
+        const requestBody = JSON.stringify(
+          batch.map((isin) => ({ idType: "ID_ISIN", idValue: isin }))
+        );
+        let response = null;
+        for (let attempt = 0; attempt < 2; attempt++) {
+          try {
+            const r = await _httpPost(
+              "https://api.openfigi.com/v3/mapping",
+              requestBody,
+              1e4
+            );
+            if (r.status < 500) {
+              response = r;
+              break;
+            }
+          } catch {
+            throw new ClassificationError("NETWORK_ERROR");
           }
-        } catch {
+        }
+        if (response === null) {
           throw new ClassificationError("NETWORK_ERROR");
         }
-      }
-      if (response === null) {
-        throw new ClassificationError("NETWORK_ERROR");
-      }
-      const results = JSON.parse(response.data);
-      for (let j = 0; j < batch.length; j++) {
-        const isin = batch[j];
-        const result = results[j];
-        const product = isinToProduct.get(isin) ?? isin;
-        if (!result || result.error || !result.data || result.data.length === 0) {
-          warnings.push(
-            `Unrecognized type: unknown. Please classify manually.`
-          );
-          newEntries[isin] = {
-            product,
-            assetClass: "Stock",
-            bucketGain: "B",
-            bucketLoss: "B",
-            taxRate: 0,
-            whiteListed: null,
-            confirmedByUser: false,
-            source: "user"
-          };
-          continue;
+        const results = JSON.parse(response.data);
+        for (let j = 0; j < batch.length; j++) {
+          const isin = batch[j];
+          const result = results[j];
+          const product = isinToProduct.get(isin) ?? isin;
+          if (!result || result.error || !result.data || result.data.length === 0) {
+            warnings.push(
+              `Unrecognized type for ${isin}: unknown. Please classify manually.`
+            );
+            newEntries[isin] = {
+              product,
+              assetClass: "Stock",
+              bucketGain: "B",
+              bucketLoss: "B",
+              taxRate: 0,
+              whiteListed: null,
+              confirmedByUser: false,
+              source: "user"
+            };
+            continue;
+          }
+          const st = result.data[0]?.securityType;
+          const st2 = result.data[0]?.securityType2;
+          const typeToUse = st && isKnownType(st) ? st : st2 && isKnownType(st2) ? st2 : st ?? st2 ?? "Unknown";
+          newEntries[isin] = classifyByType(isin, typeToUse, product, warnings);
         }
-        const st = result.data[0]?.securityType;
-        const st2 = result.data[0]?.securityType2;
-        const typeToUse = st && isKnownType(st) ? st : st2 && isKnownType(st2) ? st2 : st ?? st2 ?? "Unknown";
-        newEntries[isin] = classifyByType(isin, typeToUse, product, warnings);
+        const batchIndex = i / BATCH_SIZE;
+        options?.onBatchProgress?.(batchIndex + 1, totalBatches);
       }
     }
     const mergedMap = { ...newEntries, ...confirmed };
-    const sidecarContent = JSON.stringify(
-      {
-        version: 1,
-        generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        classifications: mergedMap,
-        warnings
-      },
-      null,
-      2
-    );
-    try {
-      fs2.writeFileSync(sidecarPath, sidecarContent, "utf-8");
-    } catch {
-      throw new ClassificationError("WRITE_ERROR");
+    if (sidecarPath !== void 0) {
+      const sidecarContent = JSON.stringify(
+        {
+          version: 1,
+          generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          classifications: mergedMap,
+          warnings
+        },
+        null,
+        2
+      );
+      try {
+        fs2.writeFileSync(sidecarPath, sidecarContent, "utf-8");
+      } catch {
+        throw new ClassificationError("WRITE_ERROR");
+      }
     }
     return mergedMap;
   }