🏃 Usage on mosty

Excel ファイルの前提

Fri, 25 Sep 2026 00:00:00 +0000

mosty は、次のような構造の Excel ファイル（.xlsx、.xlsm）を想定しています。

📄 シートの構造
#

1 つのファイルに、複数のシートがある。
各シートは 1 行が 1 人の学生 を表す表になっている。
各行の先頭の数列（既定では A〜C 列）に、学生証番号 と氏名がある。
- どちらが左でも構いません。
表の上に、タイトルや見出しの行があっても構いません。
表の途中に、空行、小見出しの行、集計の行があっても構いません。学生証番号のない行は、学生の行として扱いません。
表が A1 から始まっていなくても構いません。

例:

	A	B	C	D	E
1	課題の成績
2
3	学生証番号	氏名	課題1	課題2	合計
4	1234001	京都太郎	8	9	`=SUM(C4:D4)`
5	1234002	京産花子	10	8	`=SUM(C5:D5)`

配点表やメモのように、学生の行を持たないシートがあっても構いません。そのようなシートは検証の対象外になります。

設定ファイルを作る（init）

Fri, 25 Sep 2026 00:00:00 +0000

mosty init は、Excel ファイルの各シートについて、学生証番号の列、氏名の列、学生の行の範囲を推定し、設定ファイルに書き出します。

🚀 使い方
#

mosty init grades.xlsx

grades.xlsx と同じディレクトリに、設定ファイル mosty.grades.xlsx.json5 を書き出します。

Analyze the Excel files and write the config files (pass 1)

Usage: mosty init [OPTIONS] <EXCEL_FILEs>...

Arguments:
 <EXCEL_FILEs>... The target Excel files (.xlsx, .xlsm)

Options:
 -p, --id-pattern <REGEX> Specify the pattern of student ids [default: ^[0-9]{7}$]
 -C, --max-column <INDEX> Specify the last column index (0-origin) to search student ids and names [default: 2]
 -o, --output <FILE> Specify the destination of the config file (`-` means stdout)
 -f, --force Overwrite the existing config files
 -l, --level <LEVEL> Specify the log level [default: warn] [possible values: error, warn, info, debug, trace, off]
 -h, --help Print help (see more with '--help')

オプション	説明
`-p, --id-pattern`	学生証番号の正規表現（Excel ファイルの前提）。
`-C, --max-column`	学生証番号と氏名を探す最後の列。0 始まりの番号で、既定の `2` は A〜C 列を意味します。D 列まで探すなら `3` です。
`-o, --output`	設定ファイルの書き出し先。`-` を指定すると標準出力に出します。Excel ファイルを 1 つだけ指定したときに使えます。
`-f, --force`	設定ファイルがすでにあるときに上書きします。指定しないと、上書きせずにエラーになります。

複数の Excel ファイルを指定すると、それぞれの設定ファイルを書き出します。

参照を検証する（check）

Fri, 25 Sep 2026 00:00:00 +0000

mosty check は、設定ファイルに従って、シートをまたいだ参照が正しい学生の行を指しているかを検証します。 mosty verify でも同じように動きます。

🚀 使い方
#

mosty check grades.xlsx

grades.xlsx と同じディレクトリの mosty.grades.xlsx.json5 を読み込んで検証します。

Verify the cross-sheet references with the config files (pass 2)

Usage: mosty check [OPTIONS] <EXCEL_FILEs>...

Arguments:
 <EXCEL_FILEs>... The target Excel files (.xlsx, .xlsm)

Options:
 -c, --config <FILE> Specify the config file
 -p, --id-pattern <REGEX> Specify the pattern of student ids
 --no-init Exit with an error when the config file is missing, instead of running `init`
 -o, --output <FILE> Specify the destination of the results (`-` means stdout) [default: -]
 -F, --format <FORMAT> Specify the output format of the results [default: default] [possible values: default, json, markdown]
 -l, --level <LEVEL> Specify the log level [default: warn] [possible values: error, warn, info, debug, trace, off]
 -h, --help Print help (see more with '--help')

オプション	説明
`-c, --config`	設定ファイルを指定します。Excel ファイルを 1 つだけ指定したときに使えます。
`-p, --id-pattern`	学生証番号の正規表現。設定ファイルの `id_pattern` より優先します。
`--no-init`	設定ファイルがないときに、`mosty init` を実行せずにエラーにします。
`-o, --output`	検証結果の書き出し先。省略したときと `-` のときは標準出力に出します。
`-F, --format`	検証結果の出力形式（`default`、`json`、`markdown`）。

複数の Excel ファイルを指定すると、それぞれを検証し、結果をまとめて出力します。一部のファイルが読めなくても、検証できたファイルの結果は出力します。

検出される問題

Fri, 25 Sep 2026 00:00:00 +0000

mosty check が検出する問題の種類と、直し方をまとめます。括弧内は、JSON 形式で出力したときの kind の値です。

🔀 学生証番号の不一致（`id_mismatch`）
#

最終成績!C4 (1234003 山田 一郎) -> 課題!E7 (1234004 佐藤 次郎): student id mismatch

参照元の行の学生と、参照先の行の学生が異なります。いわゆる「1 行ずれ」です。

よくある原因: 参照先のシートで行を挿入・削除した、数式をコピーしたときに参照がずれた、など。
直し方: 参照元の数式が、同じ学生の行を指すように直します。同じ列で連続して報告されている場合は、途中から行がずれていることが多いので、ずれ始めた行を探してください。

氏名のセルが別の行を参照している場合も、この問題として報告します。学生証番号と氏名を別々に名簿から参照していて、片方だけずれている場合に見つかります。

📊 複数の学生にまたがる範囲の参照（`multi_student_range`）
#

最終成績!H3 (1234002 京産 花子) -> 課題!E4:E8: range spans multiple students

ある学生の行から、複数の学生の行を含む範囲を参照しています（=SUM(課題!E4:E8)、=MAX(試験!C:C) など）。

よくある原因: 1 人分の範囲のつもりで、複数行の範囲を書いてしまった。
直し方: その学生の行だけを参照するように直します。全員の平均などを意図している場合は、学生の行ではない集計の行で計算するか、検索関数（VLOOKUP など）を使ってください。

👯 学生証番号の重複（`duplicated_id`）
#

試験: duplicated student id 1234003 at 試験!A4, 試験!A5

同じシートの学生の範囲に、同じ学生証番号が複数あります。

設定ファイル

Fri, 25 Sep 2026 00:00:00 +0000

設定ファイルは、各シートのどの行がどの学生を表しているかを書いたファイルです。 mosty init が書き出し、mosty check が読み込みます。利用者が直接書き直しても構いません。

📁 ファイル名
#

既定では、Excel ファイルと同じディレクトリの mosty.<Excel ファイル名>.json5 です。

Excel ファイル	設定ファイル
`grades.xlsx`	`mosty.grades.xlsx.json5`
`grades.xlsm`	`mosty.grades.xlsm.json5`

先頭を mosty. にしているのは、シェルで Excel ファイル名を補完するときに、設定ファイルが候補に混ざらないようにするためです。

📝 書式
#

JSON5 で書きます。JSON5 は JSON を拡張したもので、コメント（//、/* */）、末尾のカンマ、クォートなしのキーが使えます。普通の JSON で書いても構いません。

{
 id_pattern: "^[0-9]{7}$",
 sheets: {
 "名簿": {
 id_column: 0, // A 列
 name_column: 1, // B 列
 start_row: 1, // Excel の 2 行目
 end_row: 120, // Excel の 121 行目
 },
 "最終成績": {
 id_column: 1, // B 列
 name_column: 0, // A 列（氏名が学生証番号の左にある）
 start_row: 3,
 end_row: 122,
 },
 "配点": { skip: true },
 },
}

行と列の番号は 0 始まり です。列の 0 が A 列、行の 0 が Excel の 1 行目です。

🏃 Usage on mosty

Excel ファイルの前提

📄 シートの構造 #

設定ファイルを作る（init）

🚀 使い方 #

参照を検証する（check）

🚀 使い方 #

検出される問題

🔀 学生証番号の不一致（id_mismatch） #

📊 複数の学生にまたがる範囲の参照（multi_student_range） #

👯 学生証番号の重複（duplicated_id） #

設定ファイル

📁 ファイル名 #

📝 書式 #

📄 シートの構造
#

🚀 使い方
#

🚀 使い方
#

🔀 学生証番号の不一致（`id_mismatch`）
#

📊 複数の学生にまたがる範囲の参照（`multi_student_range`）
#

👯 学生証番号の重複（`duplicated_id`）
#

📁 ファイル名
#

📝 書式
#