Comparison Story: TextFinder

Comparison Story

These pages compare a single TextFinder design implemented in Rust, C++, C#, and Python. All four variants share the same three-component architecture (CommandLine, DirNav, Output) and command-line interface, so the differences show up in language idioms rather than design choices.

Each language has its own page-thread ‐ a six-page walkthrough that follows the same part order (Introduction, CmdLine, DirNav, Output, EntryPoint, Conclusion), so the reader can jump between languages at any part. Every page carries multi-language cross-links in its header for quick comparisons.

1.0 Language Threads

Language	Entry page	Status
Rust	ComparisonStory_rs_textfinder_opt.html	available
C++	ComparisonStory_CppTextFinder.html	available
C#	not yet written	planned
Python	not yet written	planned

The threads above compare design and code — how each language expresses the same architecture in its own idioms. The tables that follow on this page compare the resulting implementations by size, complexity, and performance.

2.0 Design

All four implementations share the same four-part decomposition — argument parsing, directory traversal, result formatting, and an executable that wires them together. Folder names differ per language convention, but the roles map one-to-one so the reader can move between languages without re-learning the layout.

2.1 Cross-Language Part Mapping

Role	C++	C#	Python	Rust
Argument parsing	CommandLine/	CommandLine/	CommandLine/	RustCmdLine/
Directory traversal	DirNav/	DirNav/	DirNav/	RustDirNav/
Result formatting	Output/	Output/	Output/	(merged into EntryPoint)
Executable / wiring	EntryPoint/	EntryPoint/	EntryPoint/	EntryPoint/
Independent verifier	(planned)	(planned)	(planned)	RustTfVerify/

The Rust version merges output formatting into the top-level EntryPoint crate rather than exposing it as a separate library. Verifiers for C++, C#, and Python are planned as counterparts to RustTfVerify.

2.2 Language & Toolchain Versions

Implementation	Language / Standard	Build System
CppTextFinder	C++23 (named modules)	CMake 3.28+
CsTextFinder	C# / .NET 10	`dotnet` / `CsTextFinder.sln`
PyTextFinder	Python 3.x	none (interpreted)
rs_textfinder / rs_textfinder_opt	Rust, edition 2018	Cargo

2.3 Comparison Baseline

rs_textfinder_opt is the canonical Rust implementation used when comparing designs and performance against C++, C#, and Python. rs_textfinder is the pre-optimization Rust baseline, retained so the Rust-internal optimization discussion can reference concrete before/after code. TextFinder_CodeMetrics.pdf captures the size and complexity metrics that feed the tables further down this page.

3.0 Governance

A top-level Constitution.md governs agent work across all four implementations: edits are confined to the TextFinder/ subtree, and any request whose scope, target implementation, or intended effect is ambiguous is answered with a question rather than a guess. Each implementation (CppTextFinder/, CsTextFinder/, PyTextFinder/, rs_textfinder_opt/) then carries its own Constitution.md that governs design decisions specific to that language. The discipline keeps the four variants aligned closely enough for the cross-language comparison to be meaningful.

Constitution.md — TextFinder

Governing directives for any agent (Claude Code or otherwise) working in this project. These rules apply to the whole TextFinder tree and take precedence over general defaults.

Per-implementation Constitution.md files (under CppTextFinder/, CsTextFinder/, PyTextFinder/, rs_textfinder_opt/, etc.) govern the design of each implementation. This document governs agent behavior across all of them.

Directives

1. Stay inside the TextFinder directory

Edit, create, or delete files only within Code/Projects/TextFinder/ and its subdirectories.
Do not modify files elsewhere in the repository — including sibling Code/ folders, root-level HTML/CSS/JS, or shared site assets — without explicit authorization for that specific change.
Read-only access to files outside TextFinder is permitted when needed for context (e.g. checking site conventions), but any resulting edit must target a file inside TextFinder.

2. Think carefully; ask when ambiguous

Before acting on a request, restate the intent to yourself and check that the requested change is unambiguous in scope (which files), target (which implementation — Cpp, Cs, Py, Rust, or all), and effect (what the change is meant to accomplish).
If any of scope, target, or effect is unclear — stop and ask before editing. Do not guess, do not pick the “most likely” interpretation, and do not proceed with a partial answer.
When a request could reasonably apply to more than one implementation (e.g. “update the verifier”), ask which one is meant unless the context makes it obvious.

4.0 Performance

Timings over 20 warm-cache runs (first discarded), searching the NewSite root for class across source files. Median = average of the 10th and 11th sorted values.

TextFinder	Files Visited	Files Matched	Min (s)	Median (s)	Max (s)
PyTextFinder	1196	656	0.222	0.281	0.715
EntryPointOpt	1196	656	0.536	0.610	1.034
CppTextFinder	1196	656	0.568	0.647	0.706
CsTextFinder	1196	656	0.827	1.053	1.456
EntryPoint	1196	656	0.873	0.905	1.402

All five agree on 656 matched files, confirming behavioral equivalence. Elevated max values for EntryPointOpt, CsTextFinder, and EntryPoint reflect OS scheduling interrupts during a run, not intrinsic tool cost — the medians are more representative of steady-state performance.

5.0 Code Metrics

Generated by code_metrics.py from the Projects directory. Lines = total line count (code + comments + blanks). Scopes = scope-opening tokens: { count for brace languages; lines ending with : for Python.

CppTextFinder

File	Lines	Scopes
CommandLine\src\CmdLine.ixx	126	29
CommandLine\src\test.cpp	225	79
DirNav\src\DirNav.ixx	126	19
DirNav\src\test.cpp	491	82
EntryPoint\src\main.cpp	67	8
EntryPoint\src\test.cpp	435	59
generate_part.py	339	28
Output\src\Output.ixx	110	17
Output\src\test.cpp	469	70
TOTAL	2388	391

CsTextFinder

File	Lines	Scopes
CommandLine\CmdLine.cs	91	11
CommandLine\Test.cs	50	12
DirNav\DirNav.cs	87	16
DirNav\Test.cs	184	47
EntryPoint\Program.cs	57	14
EntryPoint\Test.cs	138	35
generate_part.py	159	14
Output\Output.cs	66	20
Output\Test.cs	166	37
TOTAL	998	206

PyTextFinder

File	Lines	Scopes
CommandLine\cmd_line.py	90	20
CommandLine\test_cmd_line.py	70	20
DirNav\dir_nav.py	80	23
DirNav\test_dir_nav.py	153	35
EntryPoint\PyTextFinder.py	70	9
EntryPoint\test_main.py	115	35
generate_part.py	156	12
Output\output.py	57	20
Output\test_output.py	114	33
TOTAL	905	207

RsTextFinder

File	Lines	Scopes
RustCmdLine\examples\test1.rs	43	15
RustCmdLine\src\cmd_line_lib.rs	242	52
RustDirNav\examples\test1.rs	77	14
RustDirNav\src\dir_nav_lib.rs	294	53
EntryPoint\src\text_finder.rs	297	77
RustTfVerify\src\main.rs	760	137
TOTAL	1715	348

RsTextFinderOpt

File	Lines	Scopes
RustCmdLine\examples\test1.rs	43	15
RustCmdLine\src\cmd_line_lib.rs	243	52
RustDirNav\examples\test1.rs	77	14
RustDirNav\src\dir_nav_lib.rs	292	52
EntryPoint\src\text_finder.rs	319	78
RustTfVerify\src\main.rs	760	137
TOTAL	1736	348