cifter-cli 0.3.0

C/C++ の関数実装を抽出する軽量 CLI

cifter

cifter は、C/C++ の関数実装を機械的かつ高速に抽出する CLI です。 tree-sitter で構文を捉え、行番号付き text として返します。重い意味解析や LLM 連携は行いません。

概要

• 単一の --source ファイルから抽出します
• 公開サブコマンドは function / flow / path の 3 つです
• 出力は元ソースと対応付け可能な行番号付き text です
• --language auto|c|cpp で解析言語を制御できます
• -D NAME[=VALUE] により条件分岐前処理を評価できます
• 出力先が TTY の場合は既定でシンタックスハイライトします

Why cifter

• 関数全体をそのまま抜き出したい
• 分岐の骨格だけを見たい
• 特定の route だけを細く追いたい
• 元の行番号を失わずにレビューや調査へ貼りたい

Installation

PyPI から install:

python -m pip install cifter-cli

最小確認:

cift --version
cift --help
python -m cifter --version
python -m cifter --help

GitHub Release の wheel / sdist から install することもできます。

python -m pip install ./cifter_cli-0.3.0-py3-none-any.whl

開発用:

uv sync
uv run cift --help

Quick Start

サンプルソース foo.c:

int DecideState(int x)
{
    int state = 0;
    LogStart();

    if (x > 0) {
        Prepare();
        state = 1;
    } else {
        PrepareFallback();
        state = 2;
    }

    Finalize();
    return state;
}

まず全体を確認したいときは、関数をそのまま抜きます。

cift function --name DecideState --source foo.c

1: int DecideState(int x)
2: {
3:     int state = 0;
4:     LogStart();
5:
6:     if (x > 0) {
7:         Prepare();
8:         state = 1;
9:     } else {
10:         PrepareFallback();
11:         state = 2;
12:     }
13:
14:     Finalize();
15:     return state;
16: }

分岐の骨格と、見たい値更新だけを薄く追いたいときは flow を使います。

cift flow --function DecideState --source foo.c --track state

1: int DecideState(int x)
2: {
3:     int state = 0;
        ...
6:     if (x > 0) {
            ...
8:         state = 1;
9:     } else {
            ...
11:         state = 2;
12:     }
        ...
15:     return state;
16: }

失敗側や else 側の 1 本だけを追って、その後に何が起きるかまで見たいときは path を使います。

cift path --function DecideState --source foo.c --route 'else'

1: int DecideState(int x)
2: {
        ...
6:     if (x > 0) {
            ...
9:     } else {
10:         PrepareFallback();
11:         state = 2;
12:     }
        ...
14:     Finalize();
15:     return state;
16: }

Commands

バージョン表示:

cift --version
python -m cifter --version

function: 指定した関数の実装全体をそのまま抽出します。レビュー対象の最小切り出しに向きます。

cift function --name FooFunction --source examples/demo.c
cift function --name HeaderCpp --source include/foo.h --language cpp

flow: 制御構造の骨格だけを残します。--track を付けると、完全一致したアクセスパスを含む文を追加保持します。

cift flow --function FooFunction --source examples/demo.c --track state
cift flow --function FooFunction --source examples/demo.c --track 'ctx->state'

path: 指定した route を細く抽出します。--route は複数回指定でき、複数指定時は OR で union します。親構造は残し、route 終端の文を含むコンテナでは、その直後に続く通常文だけを残します。

cift path --function FooFunction --source examples/demo.c --route 'case[CMD_HOGE]/if[ret == OK]'
cift path --function FooFunction --source examples/demo.c --route 'case[CMD_HOGE]/else-if[errno == EINT]'
cift path --function ElseRoute --source examples/demo.c --route 'else'
cift path --function FooFunction --source examples/demo.c --route 'case[CMD_LOOP]/while[(ctx->retry_count < 2)]/if[(ctx->retry_count == 1)]' --route 'case[CMD_LOOP]/for'

Preprocessor / Track / Route

--language: 解析言語を auto / c / cpp から選びます。.h や未知拡張子では auto が parse quality の高い方を選びます。

cift function --name HeaderCpp --source include/foo.h --language cpp

-D: 条件分岐前処理の評価に使うマクロを追加します。

cift function --name FooFunction --source examples/demo.c -D DEF_FOO -D ENABLE_BAR=1

--track: flow で保持したいアクセスパスです。構文上の完全一致だけを扱います。

• state
• ctx->state
• a->b.c

--route: path で辿る最小 DSL です。

• 1 個以上必須で、複数回指定できます

• 複数指定時は各 route を独立に解決し、結果を OR で union します

• 表示順は元ソース行順で、指定順には依存しません

• 1 本でも DSL 不正または未一致があれば全体が失敗します

• canonical form は / 区切りです

• 詳細は docs/specs/path-route-dsl.md を参照します

• case[CMD_HOGE]

• case[CMD_HOGE]/if[ret == OK]

• case[CMD_HOGE]/else-if[errno == EINT]

• default

• else

• for

• for[i = 0; i < 4; i++]

• while[ret > 0]

• do-while[ret > 0]

--route の最小サンプル集:

cift path --source examples/demo.c --function FooFunction --route 'case[CMD_HOGE]'
cift path --source examples/demo.c --function FooFunction --route 'case[CMD_LOOP]/while'
cift path --source examples/demo.c --function FooFunction --route 'case[CMD_LOOP]/while/if[(ctx->retry_count == 1)]'
cift path --source examples/demo.c --function FooFunction --route 'case[CMD_HOGE]/else-if[(ret == 11)]'

Limitations

• 対象は C/C++ のみです
• 入力は単一ファイルのみです
• 出力形式は text のみです
• 入力文字コードは UTF-8 または UTF-8 with BOM のみ対応です
• 改行コードは LF と CRLF のみ対応です
• .h と未知拡張子は --language auto で parse quality の高い方を選びます
• --track は名前解決やスコープ解析を行いません
• 演算子オーバーロード名の関数探索は未対応です
• ループ経路、goto 横断、意味解析、CFG 構築、JSON 出力は対象外です

Diagnostics

• 解析結果の標準出力契約は変わりません
• 解析品質が低い成功ケースでは、標準エラーへ quality[...] と repro: を出します
• quality[parse]: tree-sitter の ERROR / MISSING を検出したとき
• quality[preprocess]: active 領域に未対応ディレクティブが混在したとき
• quality[input]: BOM 除去や CRLF 正規化を行ったとき

Examples

リポジトリには examples/demo.c を含めています。

cift function --name FooFunction --source examples/demo.c
cift function --name FooFunction --source examples/demo.c --color
cift function --name FooFunction --source examples/demo.c --no-color
cift function --name HeaderCpp --source include/foo.h --language cpp
cift flow --function FooFunction --source examples/demo.c --track 'ctx->state'
cift path --function FooFunction --source examples/demo.c --route 'case[CMD_LOOP]/if[ret == OK]'
cift path --function FooFunction --source examples/demo.c --route 'case[CMD_LOOP]/while[(ctx->retry_count < 2)]/if[(ctx->retry_count == 1)]' --route 'case[CMD_LOOP]/for'

Development

開発者向け文書は docs/ にまとめています。

• docs/overview.md
• docs/cli.md
• docs/path-route-dsl.md
• docs/output-format.md
• docs/pipeline.md
• docs/data-model.md
• docs/architecture.md
• docs/performance.md
• docs/release.md

仕様の正本は docs/specs/ にあります。

License

MIT License で配布します。詳細は LICENSE を参照してください。