preflight-kit 0.2.0__py3-none-any.whl

preflight_kit/cli.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+import argparse
+import csv
+import os
+
+from .loader import load_csv
+from .engine import run_engine
+from .fixer import apply_fixes
+from .reporters import write_errors_csv, render_report_md
+from .models import Severity, ImportIntent
+
+
+def _write_fixed_csv(header, rows, path):
+    with open(path, "w", newline="", encoding="utf-8") as fh:
+        writer = csv.writer(fh)
+        writer.writerow(header)
+        writer.writerows(rows)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="preflight")
+    sub = parser.add_subparsers(dest="command", required=True)
+    check = sub.add_parser("check", help="Validate a Shopify product CSV")
+    check.add_argument("input")
+    check.add_argument("--out-dir", default="./out")
+    check.add_argument("--lang", choices=["ja", "en"], default="ja")
+    check.add_argument("--no-fix", action="store_true")
+    check.add_argument("--intent", choices=["new", "update", "mixed"], default="mixed")
+    args = parser.parse_args(argv)
+
+    intent = ImportIntent(args.intent)
+    load = load_csv(args.input)
+    findings = run_engine(load, intent)
+
+    os.makedirs(args.out_dir, exist_ok=True)
+
+    # fixer を errors.csv 書き込みより**先**に走らせる。apply_fixes は適用済み Finding を
+    # auto_fixed=True に mutate するため、errors.csv にその最終状態を反映させる（round-5 #1）。
+    # F01b（非 UTF-8）検出時は fixed_products.csv を出さない。loader は replace 文字で
+    # デコードしているため、そのまま書き出すと元データを破壊する（#7）。
+    # parse_skipped（15MB 超で行未 parse）時も出さない。rows=[] のまま書くと元 CSV を
+    # 空ファイルへ置き換えてしまい、ユーザーが F04a critical を見落として空 fixed を
+    # 使うとデータ破損になる（round-2 blocking）。F04a で import 不可なので fixed 不要。
+    non_utf8 = load.encoding == "unknown"
+    applied = []
+    if not args.no_fix and not load.blocked and not non_utf8 and not load.parse_skipped:
+        fix = apply_fixes(load, findings)
+        applied = fix.applied
+        _write_fixed_csv(
+            fix.header, fix.rows, os.path.join(args.out_dir, "fixed_products.csv")
+        )
+
+    # auto_fixed 状態が確定してから errors.csv を書く。
+    write_errors_csv(findings, os.path.join(args.out_dir, "errors.csv"))
+
+    group_count = len({r.product_group_id for r in load.rows if r.product_group_id})
+    report = render_report_md(
+        findings,
+        lang=args.lang,
+        scanned_rows=len(load.rows),
+        group_count=group_count,
+        applied=applied,
+    )
+    with open(os.path.join(args.out_dir, "report.md"), "w", encoding="utf-8") as fh:
+        fh.write(report)
+
+    has_critical = any(f.severity == Severity.CRITICAL for f in findings)
+    return 1 if has_critical else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

preflight_kit/engine.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from .loader import LoadResult
+from .models import Finding, ImportIntent
+from .header_registry import CANONICAL_TO_HEADERS
+from .rules import ALL_RULES
+from .rules.file_rules import rule_f04a
+
+
+def _build_field_display_map(load: LoadResult) -> dict[str, str]:
+    """ルールがハードコードする primary 列名 -> その CSV で実際に使われた元列名。
+
+    spec: errors.csv の `field` は「元の列名で表示」する。ルールは primary 名
+    （例 `URL handle`/`SKU`）を field に渡すため、旧 alias 入力（例 `Handle`/
+    `Variant SKU`）では実在しない列名が出てしまう（round-1 non-blocking）。
+    canonical key 経由で逆引きし、実入力の列名へ置換するマップを作る。
+    """
+    # canonical key -> 実際の元列名。同一 canonical key に複数の元列名がある場合
+    # （例 `Handle` と `URL handle` が両方 handle に対応）、loader の row.canonical は
+    # header 順の dict 内包で構築され **後勝ち**（最後に現れた列の値が残る）。よって
+    # ルールが実際に参照している値は最後の列のものなので、display も最後の列名を採用し
+    # 整合させる（setdefault=最初優先だと値とラベルがずれる・round-2 non-blocking）。
+    key_to_original: dict[str, str] = {}
+    for original_col, key in load.canonical_map.items():
+        key_to_original[key] = original_col  # 後勝ち（row.canonical と一致）
+    # primary 名（ルールが渡す値・CANONICAL_TO_HEADERS 先頭） -> 実際の元列名。
+    # primary == 実列名のとき（新形式入力）は置換不要なので除く。
+    display: dict[str, str] = {}
+    for key, original in key_to_original.items():
+        primary = CANONICAL_TO_HEADERS.get(key, [None])[0]
+        if primary is not None and primary != original:
+            display[primary] = original
+    return display
+
+
+def run_engine(load: LoadResult, intent: ImportIntent) -> list[Finding]:
+    findings: list[Finding] = list(load.file_findings)
+    if load.blocked:
+        # PII ガード等で停止。値・列の中身を見るルールは走らせない。
+        # ただし F04a（15MB hard limit）は raw_byte_size だけで決まり、import 可否に
+        # 直結する critical なので、PII 停止時でも必ず出す（round-3 blocking: 15MB 超 +
+        # PII で F04a が false negative になっていた）。F04a は header/rows を参照しない
+        # ため blocked 状態でも安全に評価できる。
+        findings.extend(rule_f04a(load, intent))
+        return findings
+    # parse_skipped でヘッダーすら読めなかった（巨大セルで csv.Error）場合、列構造が
+    # 不明なため F03c（必須列欠落）は判定不能。これを通常実行すると header=[] を根拠に
+    # title/handle 欠落を誤発火する（round-3 non-blocking）。F04a critical に委ね、
+    # 列構造が読めていない F03c はスキップする。ヘッダーが読めた parse_skipped（巨大
+    # product CSV）では header 非空なので F03c は正しく機能する（列があれば出ない）。
+    skip_f03c = load.parse_skipped and not load.header
+    for rule in ALL_RULES:
+        if skip_f03c and getattr(rule, "__name__", "") == "rule_f03c":
+            continue
+        findings.extend(rule(load, intent))
+    # field を実入力の元列名へ正規化（spec: 元の列名で表示）。
+    display = _build_field_display_map(load)
+    if display:
+        for f in findings:
+            if f.field in display:
+                f.field = display[f.field]
+    return findings

preflight_kit/fixer.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+from dataclasses import dataclass
+
+from .loader import LoadResult
+from .models import Finding, FixClass
+from .header_registry import to_canonical, CANONICAL_TO_HEADERS
+
+
+@dataclass
+class FixResult:
+    header: list[str]
+    rows: list[list[str]]
+    applied: list[Finding]
+
+
+def _is_proven(f: Finding) -> bool:
+    # spec: fix_class==proven かつ auto_fixable==True の両方を要求（#6）。
+    return f.fix_class == FixClass.PROVEN and f.auto_fixable
+
+
+def apply_fixes(load: LoadResult, findings: list[Finding]) -> FixResult:
+    applied: list[Finding] = []
+
+    # F01a（BOM 除去）は loader が既にバイト列から除去済み。fixer は適用済みとして
+    # applied に取り込み auto_fixed=True にする（#5: report に proven 適用を出す）。
+    applied.extend(f for f in findings if f.rule_id == "F01a" and _is_proven(f))
+
+    # F03a: header case-only 修正（proven）。元列名 -> canonical 正式名へ。
+    f03a_cols = {f.field for f in findings if f.rule_id == "F03a" and _is_proven(f)}
+    new_header: list[str] = []
+    for col in load.header:
+        if col in f03a_cols:
+            key = to_canonical(col)
+            primary = CANONICAL_TO_HEADERS[key][0] if key else col
+            new_header.append(primary)
+        else:
+            new_header.append(col)
+    applied.extend(f for f in findings if f.rule_id == "F03a" and _is_proven(f))
+
+    # 行は列順を保持して元の値をそのまま出す（行順保持）。
+    # F04c の余剰セル（extra_cells）は silent discard せず末尾へそのまま付ける。
+    out_rows: list[list[str]] = []
+    for row in load.rows:
+        out_rows.append(
+            [row.cells.get(col, "") for col in load.header] + list(row.extra_cells)
+        )
+
+    for f in applied:
+        f.auto_fixed = True
+    return FixResult(header=new_header, rows=out_rows, applied=applied)

preflight_kit/header_registry.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+import re
+
+# canonical key -> [新形式ヘッダー, 旧形式 alias...]（先頭が canonical 正式名）
+CANONICAL_TO_HEADERS: dict[str, list[str]] = {
+    "handle": ["URL handle", "Handle"],
+    "title": ["Title"],
+    "description": ["Description", "Body (HTML)"],
+    "vendor": ["Vendor"],
+    "product_category": ["Product category", "Product Category"],
+    "type": ["Type"],
+    "tags": ["Tags"],
+    "published": ["Published on online store", "Published"],
+    "status": ["Status"],
+    "sku": ["SKU", "Variant SKU"],
+    "barcode": ["Barcode", "Variant Barcode"],
+    "option1_name": ["Option1 name", "Option1 Name"],
+    "option1_value": ["Option1 value", "Option1 Value"],
+    "option1_linkedto": ["Option1 LinkedTo", "Option1 Linked To"],
+    "option2_name": ["Option2 name", "Option2 Name"],
+    "option2_value": ["Option2 value", "Option2 Value"],
+    "option2_linkedto": ["Option2 LinkedTo", "Option2 Linked To"],
+    "option3_name": ["Option3 name", "Option3 Name"],
+    "option3_value": ["Option3 value", "Option3 Value"],
+    "option3_linkedto": ["Option3 LinkedTo", "Option3 Linked To"],
+    "price": ["Price", "Variant Price"],
+    "compare_at_price": ["Compare-at price", "Variant Compare At Price"],
+    "cost_per_item": ["Cost per item", "Cost per item (USD)"],
+    "inventory_tracker": ["Inventory tracker", "Variant Inventory Tracker"],
+    "inventory_qty": ["Inventory quantity", "Variant Inventory Qty"],
+    "inventory_policy": [
+        "Continue selling when out of stock",
+        "Variant Inventory Policy",
+    ],
+    "fulfillment_service": ["Fulfillment service", "Variant Fulfillment Service"],
+    "weight_value": ["Weight value (grams)", "Variant Grams"],
+    "weight_unit": ["Weight unit for display", "Variant Weight Unit"],
+    "requires_shipping": ["Requires shipping", "Variant Requires Shipping"],
+    "charge_tax": ["Charge tax", "Variant Taxable"],
+    "gift_card": ["Gift card", "Gift Card"],
+    "image_src": ["Product image URL", "Image Src"],
+    "image_position": ["Image position", "Image Position"],
+    "variant_image": ["Variant image URL", "Variant Image"],
+    "image_alt": ["Image alt text", "Image Alt Text"],
+    "seo_title": ["SEO title", "SEO Title"],
+    "seo_description": ["SEO description", "SEO Description"],
+    "collection": ["Collection"],
+}
+
+# 注意（実装者向け）: 上表は repo sample + spec 必須列 + 現行公式 CSV の主要列を含むが、
+# Task 1（rules spec）で公式 current CSV 全列を確定し、ここに無い現行列があれば必ず追加する。
+# 出典: https://help.shopify.com/en/manual/products/import-export/using-csv
+# 怠ると F03d が有効な公式列を unknown warning として誤検出する（round-3 #1 の根本対策）。
+
+# 元ヘッダー(lower) -> canonical key
+_HEADER_LOWER_TO_KEY: dict[str, str] = {}
+# 元ヘッダー(正確) -> canonical key
+_HEADER_EXACT_TO_KEY: dict[str, str] = {}
+# canonical 正式名(新形式)の集合（先頭要素）
+_CANONICAL_PRIMARY: set[str] = set()
+# canonical 正式名(新形式)の lower -> primary（case-only 判定を primary に限定する。
+# alias の大小違いを case_only と誤判定して proven 改名するのを防ぐ・round-3 #2）
+_PRIMARY_LOWER_TO_KEY: dict[str, str] = {}
+for _key, _headers in CANONICAL_TO_HEADERS.items():
+    _primary = _headers[0]
+    _CANONICAL_PRIMARY.add(_primary)
+    _PRIMARY_LOWER_TO_KEY[_primary.lower()] = _key
+    for _i, _h in enumerate(_headers):
+        _HEADER_EXACT_TO_KEY[_h] = _key
+        _HEADER_LOWER_TO_KEY[_h.lower()] = _key
+
+# dynamic 列パターン（registry に列挙不能な可変ヘッダー。誤検出も誤変換もしない）。
+# round-4 #1: Markets 価格列の market 名は可変（International だけでない）。
+# product metafield は `Metafield:` 接頭辞 / `(...product.metafields...)` / bare
+# `product.metafields.<ns>.<key>` の3形式がある。variant metafield は除外する。
+_DYNAMIC_PATTERNS = [
+    re.compile(r"^Metafield:", re.IGNORECASE),
+    re.compile(r"product\.metafields\.", re.IGNORECASE),  # 括弧付き/ bare 両対応
+    re.compile(r"^Google Shopping", re.IGNORECASE),
+    # Markets/地域別価格: "Price / <market>" "Compare-at price / <market>"（market 名可変）
+    re.compile(r"^(Price|Compare-at price)\s*/\s*.+", re.IGNORECASE),
+    re.compile(r"\bIncluded\b\s*/\s*.+", re.IGNORECASE),  # Markets included / <market>
+]
+# variant metafield: `Variant Metafield:` 接頭辞 / bare `variant.metafields.<ns>.<key>`。
+# dynamic より先に判定し dynamic から除外する（standard product CSV import 非対応のため警告）。
+_VARIANT_METAFIELD = re.compile(
+    r"^Variant Metafield:|variant\.metafields\.", re.IGNORECASE
+)
+
+
+def to_canonical(header: str) -> str | None:
+    if header in _HEADER_EXACT_TO_KEY:
+        return _HEADER_EXACT_TO_KEY[header]
+    return _HEADER_LOWER_TO_KEY.get(header.lower())
+
+
+def is_variant_metafield(header: str) -> bool:
+    # `^Variant Metafield:` か bare `variant.metafields.` を拾う（search で両対応）。
+    return bool(_VARIANT_METAFIELD.search(header))
+
+
+def is_dynamic(header: str) -> bool:
+    if is_variant_metafield(header):
+        return False
+    return any(p.search(header) for p in _DYNAMIC_PATTERNS)
+
+
+def match_kind(header: str) -> str:
+    if header in _CANONICAL_PRIMARY:
+        return "canonical"
+    key = _HEADER_EXACT_TO_KEY.get(header)
+    if key is not None:
+        # 完全一致だが正式名でない = 旧形式 alias（exact 一致）
+        return "alias"
+    # case_only は **現行 primary ヘッダーの大小違いのみ**。これは proven 改名対象。
+    if header.lower() in _PRIMARY_LOWER_TO_KEY:
+        return "case_only"
+    # primary でない lower 一致 = alias の大小違い。alias→canonical 改名は suggested の
+    # ため proven 化しない。alias 扱いに倒す（F03b が suggested で提案・改名しない）。
+    if header.lower() in _HEADER_LOWER_TO_KEY:
+        return "alias"
+    if is_variant_metafield(header):
+        return "variant_metafield"
+    if is_dynamic(header):
+        return "dynamic"
+    return "unknown"

preflight_kit/json_dump.py

@@ -0,0 +1,85 @@
+"""Golden crosscheck 用の読み取り専用 JSON dump（検査ロジックは一切変更しない）。
+
+`load_csv` + `run_engine` を呼び、findings を TS `reporters.ts` の `NormalizedFinding`
+と **同一スキーマ・同一 key 順・同一 full sort key** の JSON 配列で stdout 出力する。
+
+TS reporters.ts の NormalizedFinding と同期（変更時は両方）:
+  key order: ruleId, row, severity, field, fixClass, autoFixable,
+             productGroupId, rowKind, message, suggestedFix
+  sort key : ruleId, row ?? -1, severity, field ?? "", fixClass,
+             productGroupId ?? "", rowKind ?? "", message, suggestedFix
+
+使い方:
+  uv run python -m preflight_kit.json_dump <input.csv> --intent <new|update|mixed>
+"""
+
+from __future__ import annotations
+import argparse
+import json
+import sys
+
+from .loader import load_csv
+from .engine import run_engine
+from .models import Finding, ImportIntent
+
+
+def _enum_value(v) -> str | None:
+    if v is None:
+        return None
+    if hasattr(v, "value"):
+        return v.value
+    return str(v)
+
+
+def to_normalized_record(f: Finding) -> dict:
+    # key 順は TS NormalizedFinding と 1:1（dict 挿入順 = JSON 出力順）。
+    return {
+        "ruleId": f.rule_id,
+        "row": f.row,
+        "severity": _enum_value(f.severity),
+        "field": f.field,
+        "fixClass": _enum_value(f.fix_class),
+        "autoFixable": bool(f.auto_fixable),
+        "productGroupId": f.product_group_id,
+        "rowKind": _enum_value(f.row_kind),
+        "message": f.message,
+        "suggestedFix": f.suggested_fix,
+    }
+
+
+def normalize_findings(findings: list[Finding]) -> list[dict]:
+    records = [to_normalized_record(f) for f in findings]
+    # full sort key（TS normalizeFindings と同一順）。None は TS の ?? 既定に合わせる。
+    records.sort(
+        key=lambda r: (
+            r["ruleId"],
+            r["row"] if r["row"] is not None else -1,
+            r["severity"],
+            r["field"] if r["field"] is not None else "",
+            r["fixClass"],
+            r["productGroupId"] if r["productGroupId"] is not None else "",
+            r["rowKind"] if r["rowKind"] is not None else "",
+            r["message"],
+            r["suggestedFix"],
+        )
+    )
+    return records
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="preflight-kit-json-dump")
+    parser.add_argument("input")
+    parser.add_argument("--intent", choices=["new", "update", "mixed"], default="new")
+    args = parser.parse_args(argv)
+
+    intent = ImportIntent(args.intent)
+    load = load_csv(args.input)
+    findings = run_engine(load, intent)
+    records = normalize_findings(findings)
+    json.dump(records, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())