From 358cc71301a35e81101bb3167ea1e8d92f4ca255 Mon Sep 17 00:00:00 2001 From: Michael Karlesky Date: Thu, 12 Nov 2026 23:40:30 -0500 Subject: [PATCH 1/4] Gather the tool code in lib/ceedling/tools/ ToolExecutor, ToolExecutorHelper and ToolValidator move to their own directory, as the file code did in filesystem/. Their unit specs move to spec/units/tools/ alongside the default tools' quoting spec. Only require paths change. DIY finds the objects through the load path the rakefile already builds from every lib/ceedling/ subdirectory. Co-Authored-By: Claude Opus 5.5 --- .rubocop_todo.yml | 18 +++++++++--------- lib/ceedling/config/configurator.rb | 2 +- lib/ceedling/{ => tools}/tool_executor.rb | 0 .../{ => tools}/tool_executor_helper.rb | 0 lib/ceedling/{ => tools}/tool_validator.rb | 0 plugins/command_hooks/lib/command_hooks.rb | 2 +- spec/integration/tool_executor_spec.rb | 2 +- spec/integration/tool_validator_spec.rb | 4 ++-- .../configurator_integration_helper.rb | 6 +++--- .../integration/spec_integration_helper.rb | 2 +- .../tool_executor_integration_helper.rb | 4 ++-- spec/units/config/configurator_spec.rb | 2 +- .../units/plugins/console_reportinator_spec.rb | 2 +- .../reportgenerator_reportinator_spec.rb | 2 +- spec/units/preprocess/preprocessinator_spec.rb | 2 +- .../{ => tools}/default_tools_quoting_spec.rb | 10 +++++----- .../{ => tools}/tool_executor_helper_spec.rb | 2 +- spec/units/{ => tools}/tool_executor_spec.rb | 2 +- spec/units/{ => tools}/tool_validator_spec.rb | 2 +- spec/units/windows_registry_query_tool_spec.rb | 2 +- 20 files changed, 33 insertions(+), 33 deletions(-) rename lib/ceedling/{ => tools}/tool_executor.rb (100%) rename lib/ceedling/{ => tools}/tool_executor_helper.rb (100%) rename lib/ceedling/{ => tools}/tool_validator.rb (100%) rename spec/units/{ => tools}/default_tools_quoting_spec.rb (88%) rename spec/units/{ => tools}/tool_executor_helper_spec.rb (99%) rename spec/units/{ => tools}/tool_executor_spec.rb (99%) rename spec/units/{ => tools}/tool_validator_spec.rb (99%) diff --git a/.rubocop_todo.yml b/.rubocop_todo.yml index 7b8b8d0e5..4c71eaa8e 100644 --- a/.rubocop_todo.yml +++ b/.rubocop_todo.yml @@ -91,8 +91,8 @@ Metrics/AbcSize: - 'lib/ceedling/test_invoker/test_build_planner.rb' - 'lib/ceedling/test_invoker/test_build_setup.rb' - 'lib/ceedling/test_invoker/test_pipeline_manager.rb' - - 'lib/ceedling/tool_executor.rb' - - 'lib/ceedling/tool_executor_helper.rb' + - 'lib/ceedling/tools/tool_executor.rb' + - 'lib/ceedling/tools/tool_executor_helper.rb' - 'plugins/beep/lib/beep.rb' - 'plugins/bullseye/lib/bullseye.rb' - 'plugins/cppcheck/lib/cppcheck.rb' @@ -184,7 +184,7 @@ Metrics/ClassLength: - 'lib/ceedling/test_invoker/test_build_planner.rb' - 'lib/ceedling/test_invoker/test_build_setup.rb' - 'lib/ceedling/test_invoker/test_pipeline_manager.rb' - - 'lib/ceedling/tool_executor.rb' + - 'lib/ceedling/tools/tool_executor.rb' - 'plugins/bullseye/lib/bullseye.rb' - 'plugins/cppcheck/lib/cppcheck.rb' - 'plugins/dependencies/lib/dependencies.rb' @@ -237,8 +237,8 @@ Metrics/CyclomaticComplexity: - 'lib/ceedling/test_invoker/test_build_executor.rb' - 'lib/ceedling/test_invoker/test_build_planner.rb' - 'lib/ceedling/test_invoker/test_pipeline_manager.rb' - - 'lib/ceedling/tool_executor.rb' - - 'lib/ceedling/tool_executor_helper.rb' + - 'lib/ceedling/tools/tool_executor.rb' + - 'lib/ceedling/tools/tool_executor_helper.rb' - 'plugins/bullseye/lib/bullseye.rb' - 'plugins/cppcheck/lib/cppcheck.rb' - 'plugins/dependencies/lib/dependencies.rb' @@ -315,8 +315,8 @@ Metrics/MethodLength: - 'lib/ceedling/test_invoker/test_build_setup.rb' - 'lib/ceedling/test_invoker/test_invoker.rb' - 'lib/ceedling/test_invoker/test_pipeline_manager.rb' - - 'lib/ceedling/tool_executor.rb' - - 'lib/ceedling/tool_executor_helper.rb' + - 'lib/ceedling/tools/tool_executor.rb' + - 'lib/ceedling/tools/tool_executor_helper.rb' - 'lib/ceedling/yaml_wrapper.rb' - 'plugins/beep/lib/beep.rb' - 'plugins/bullseye/config/defaults_bullseye.rb' @@ -383,8 +383,8 @@ Metrics/PerceivedComplexity: - 'lib/ceedling/test_invoker/test_build_executor.rb' - 'lib/ceedling/test_invoker/test_build_planner.rb' - 'lib/ceedling/test_invoker/test_pipeline_manager.rb' - - 'lib/ceedling/tool_executor.rb' - - 'lib/ceedling/tool_executor_helper.rb' + - 'lib/ceedling/tools/tool_executor.rb' + - 'lib/ceedling/tools/tool_executor_helper.rb' - 'plugins/bullseye/lib/bullseye.rb' - 'plugins/cppcheck/lib/cppcheck.rb' - 'plugins/fff/lib/fff_mock_generator.rb' diff --git a/lib/ceedling/config/configurator.rb b/lib/ceedling/config/configurator.rb index b8d57351b..96cf269e1 100644 --- a/lib/ceedling/config/configurator.rb +++ b/lib/ceedling/config/configurator.rb @@ -10,7 +10,7 @@ require 'ceedling/filesystem/file_path_utils' require 'ceedling/exceptions' require 'ceedling/rake_app/rakefile_component_resolver' -require 'ceedling/tool_executor' +require 'ceedling/tools/tool_executor' require 'deep_merge' class Configurator diff --git a/lib/ceedling/tool_executor.rb b/lib/ceedling/tools/tool_executor.rb similarity index 100% rename from lib/ceedling/tool_executor.rb rename to lib/ceedling/tools/tool_executor.rb diff --git a/lib/ceedling/tool_executor_helper.rb b/lib/ceedling/tools/tool_executor_helper.rb similarity index 100% rename from lib/ceedling/tool_executor_helper.rb rename to lib/ceedling/tools/tool_executor_helper.rb diff --git a/lib/ceedling/tool_validator.rb b/lib/ceedling/tools/tool_validator.rb similarity index 100% rename from lib/ceedling/tool_validator.rb rename to lib/ceedling/tools/tool_validator.rb diff --git a/plugins/command_hooks/lib/command_hooks.rb b/plugins/command_hooks/lib/command_hooks.rb index fb06d9010..119063802 100755 --- a/plugins/command_hooks/lib/command_hooks.rb +++ b/plugins/command_hooks/lib/command_hooks.rb @@ -8,7 +8,7 @@ require 'ceedling/constants' require 'ceedling/exceptions' require 'ceedling/plugins/plugin' -require 'ceedling/tool_executor' +require 'ceedling/tools/tool_executor' COMMAND_HOOKS_ROOT_NAME = 'command_hooks'.freeze COMMAND_HOOKS_SYM = COMMAND_HOOKS_ROOT_NAME.to_sym diff --git a/spec/integration/tool_executor_spec.rb b/spec/integration/tool_executor_spec.rb index 47e244230..8ce793f81 100644 --- a/spec/integration/tool_executor_spec.rb +++ b/spec/integration/tool_executor_spec.rb @@ -5,7 +5,7 @@ # SPDX-License-Identifier: MIT # ========================================================================= -# Unlike spec/units/tool_executor_spec.rb, this spec wires the REAL ToolExecutor + +# Unlike spec/units/tools/tool_executor_spec.rb, this spec wires the REAL ToolExecutor + # ToolExecutorHelper + SystemWrapper + SystemUtils + Loginator + Verbosinator + # RubyExpandinator graph (see tool_executor_integration_helper.rb) and genuinely shells # out through SystemWrapper#shell_capture3 (Open3.capture3). The one external dependency diff --git a/spec/integration/tool_validator_spec.rb b/spec/integration/tool_validator_spec.rb index f2fb85a76..2e9834dab 100644 --- a/spec/integration/tool_validator_spec.rb +++ b/spec/integration/tool_validator_spec.rb @@ -10,13 +10,13 @@ # Whether a candidate file exists, how a quoted path with spaces resolves, and what PATH # a process actually searches are facts a doubled file layer cannot prove. A real # FileWrapper and SystemWrapper run here against real temp directories, with PATH set -# per example. The unit spec at spec/units/tool_validator_spec.rb owns every decision +# per example. The unit spec at spec/units/tools/tool_validator_spec.rb owns every decision # observable through doubles alone. require 'spec_helper' require 'spec_integration_helper' require 'fileutils' -require 'ceedling/tool_validator' +require 'ceedling/tools/tool_validator' require 'ceedling/filesystem/file_wrapper' require 'ceedling/system_wrapper' require 'ceedling/ruby_expandinator' diff --git a/spec/support/integration/configurator_integration_helper.rb b/spec/support/integration/configurator_integration_helper.rb index d90341a09..89f8a4290 100644 --- a/spec/support/integration/configurator_integration_helper.rb +++ b/spec/support/integration/configurator_integration_helper.rb @@ -30,9 +30,9 @@ require 'ceedling/ruby_expandinator' require 'ceedling/filesystem/file_path_collection_utils' require 'ceedling/filesystem/file_path_utils' -require 'ceedling/tool_validator' -require 'ceedling/tool_executor' -require 'ceedling/tool_executor_helper' +require 'ceedling/tools/tool_validator' +require 'ceedling/tools/tool_executor' +require 'ceedling/tools/tool_executor_helper' require 'ceedling/setupinator' require 'ceedling/config/config_walkinator' require 'ceedling/config/configurator' diff --git a/spec/support/integration/spec_integration_helper.rb b/spec/support/integration/spec_integration_helper.rb index 6cd8d3855..9ba13b5bc 100644 --- a/spec/support/integration/spec_integration_helper.rb +++ b/spec/support/integration/spec_integration_helper.rb @@ -31,7 +31,7 @@ require 'ceedling/includes/includes' require 'ceedling/includes/include_factory' require 'ceedling/preprocess/preprocessinator' -require 'ceedling/tool_executor' +require 'ceedling/tools/tool_executor' require 'ceedling/quote_include_isolator' require 'ceedling/preprocess/preprocessinator_includes_handler' require 'ceedling/preprocess/preprocessinator_bare_includes_extractor' diff --git a/spec/support/integration/tool_executor_integration_helper.rb b/spec/support/integration/tool_executor_integration_helper.rb index 1b4eb88c9..f1f16e2d7 100644 --- a/spec/support/integration/tool_executor_integration_helper.rb +++ b/spec/support/integration/tool_executor_integration_helper.rb @@ -15,8 +15,8 @@ require 'rbconfig' -require 'ceedling/tool_executor' -require 'ceedling/tool_executor_helper' +require 'ceedling/tools/tool_executor' +require 'ceedling/tools/tool_executor_helper' require 'ceedling/system_wrapper' require 'ceedling/system_utils' require 'ceedling/loginator' diff --git a/spec/units/config/configurator_spec.rb b/spec/units/config/configurator_spec.rb index f9a9cad4f..297257e1d 100644 --- a/spec/units/config/configurator_spec.rb +++ b/spec/units/config/configurator_spec.rb @@ -10,7 +10,7 @@ require 'ceedling/ruby_expandinator' require 'ceedling/exceptions' require 'ceedling/constants' -require 'ceedling/tool_executor' +require 'ceedling/tools/tool_executor' require 'ceedling/config/config_walkinator' require 'ceedling/config/configurator_builder' require 'ceedling/system_utils' diff --git a/spec/units/plugins/console_reportinator_spec.rb b/spec/units/plugins/console_reportinator_spec.rb index f7454f1dc..2df21bdcf 100644 --- a/spec/units/plugins/console_reportinator_spec.rb +++ b/spec/units/plugins/console_reportinator_spec.rb @@ -7,7 +7,7 @@ require 'spec_helper' require 'ceedling/filename_extension' -require 'ceedling/tool_executor' +require 'ceedling/tools/tool_executor' require 'ceedling/constants' require 'ceedling/exceptions' require 'ceedling/filesystem/path_mirror' diff --git a/spec/units/plugins/reportgenerator_reportinator_spec.rb b/spec/units/plugins/reportgenerator_reportinator_spec.rb index 5e0f15031..873df58d7 100644 --- a/spec/units/plugins/reportgenerator_reportinator_spec.rb +++ b/spec/units/plugins/reportgenerator_reportinator_spec.rb @@ -6,7 +6,7 @@ # ========================================================================= require 'spec_helper' -require 'ceedling/tool_executor' +require 'ceedling/tools/tool_executor' require 'ceedling/constants' require 'ceedling/exceptions' require 'ceedling/filesystem/file_path_utils' diff --git a/spec/units/preprocess/preprocessinator_spec.rb b/spec/units/preprocess/preprocessinator_spec.rb index a17a3c717..942f2b6e0 100644 --- a/spec/units/preprocess/preprocessinator_spec.rb +++ b/spec/units/preprocess/preprocessinator_spec.rb @@ -8,7 +8,7 @@ require 'spec_helper' require 'ceedling/preprocess/preprocessinator' require 'ceedling/includes/includes' -require 'ceedling/tool_executor' +require 'ceedling/tools/tool_executor' RSpec.describe Preprocessinator do diff --git a/spec/units/default_tools_quoting_spec.rb b/spec/units/tools/default_tools_quoting_spec.rb similarity index 88% rename from spec/units/default_tools_quoting_spec.rb rename to spec/units/tools/default_tools_quoting_spec.rb index c7d7fb389..dd3aaa638 100644 --- a/spec/units/default_tools_quoting_spec.rb +++ b/spec/units/tools/default_tools_quoting_spec.rb @@ -9,12 +9,12 @@ require 'shellwords' require 'yaml' require 'ceedling/defaults' -require 'ceedling/tool_executor' +require 'ceedling/tools/tool_executor' require 'ceedling/ruby_expandinator' -load File.expand_path( '../../plugins/gcov/config/defaults_gcov.rb', __dir__ ) -load File.expand_path( '../../plugins/bullseye/config/defaults_bullseye.rb', __dir__ ) -load File.expand_path( '../../plugins/cppcheck/config/defaults_cppcheck.rb', __dir__ ) +load File.expand_path( '../../../plugins/gcov/config/defaults_gcov.rb', __dir__ ) +load File.expand_path( '../../../plugins/bullseye/config/defaults_bullseye.rb', __dir__ ) +load File.expand_path( '../../../plugins/cppcheck/config/defaults_cppcheck.rb', __dir__ ) # GH #1373: the default tools that run a test executable named it unquoted, so a path holding # an apostrophe or a space broke the shell command. Each command here is split as a POSIX @@ -24,7 +24,7 @@ OTHER_PATH = "src/my dir/o'neil.c" DEPENDENCIES_TOOLS = YAML.load_file( - File.expand_path( '../../plugins/dependencies/config/defaults.yml', __dir__ ), symbolize_names: true + File.expand_path( '../../../plugins/dependencies/config/defaults.yml', __dir__ ), symbolize_names: true )[:tools] before(:each) do diff --git a/spec/units/tool_executor_helper_spec.rb b/spec/units/tools/tool_executor_helper_spec.rb similarity index 99% rename from spec/units/tool_executor_helper_spec.rb rename to spec/units/tools/tool_executor_helper_spec.rb index 202344d98..07084c590 100644 --- a/spec/units/tool_executor_helper_spec.rb +++ b/spec/units/tools/tool_executor_helper_spec.rb @@ -7,7 +7,7 @@ require 'spec_helper' require 'ceedling/constants' -require 'ceedling/tool_executor_helper' +require 'ceedling/tools/tool_executor_helper' require 'ceedling/system_wrapper' require 'ceedling/loginator' require 'ceedling/system_utils' diff --git a/spec/units/tool_executor_spec.rb b/spec/units/tools/tool_executor_spec.rb similarity index 99% rename from spec/units/tool_executor_spec.rb rename to spec/units/tools/tool_executor_spec.rb index 15e479626..61ceb1bc3 100644 --- a/spec/units/tool_executor_spec.rb +++ b/spec/units/tools/tool_executor_spec.rb @@ -6,7 +6,7 @@ # ========================================================================= require 'spec_helper' -require 'ceedling/tool_executor' +require 'ceedling/tools/tool_executor' require 'ceedling/ruby_expandinator' require 'ceedling/exceptions' diff --git a/spec/units/tool_validator_spec.rb b/spec/units/tools/tool_validator_spec.rb similarity index 99% rename from spec/units/tool_validator_spec.rb rename to spec/units/tools/tool_validator_spec.rb index 8f49b92c4..f2021d82a 100644 --- a/spec/units/tool_validator_spec.rb +++ b/spec/units/tools/tool_validator_spec.rb @@ -7,7 +7,7 @@ require 'spec_helper' require 'ceedling/constants' -require 'ceedling/tool_validator' +require 'ceedling/tools/tool_validator' require 'ceedling/ruby_expandinator' require 'ceedling/filename_extension' require 'ceedling/exceptions' diff --git a/spec/units/windows_registry_query_tool_spec.rb b/spec/units/windows_registry_query_tool_spec.rb index f0487825c..18dbae930 100644 --- a/spec/units/windows_registry_query_tool_spec.rb +++ b/spec/units/windows_registry_query_tool_spec.rb @@ -7,7 +7,7 @@ require 'spec_helper' require 'ceedling/defaults' -require 'ceedling/tool_executor' +require 'ceedling/tools/tool_executor' require 'ceedling/ruby_expandinator' require 'ceedling/filesystem/win_long_paths' From 3f169e7641b98420bc8d9d633f16965ca5543620 Mon Sep 17 00:00:00 2001 From: Michael Karlesky Date: Thu, 12 Nov 2026 23:53:47 -0500 Subject: [PATCH 2/4] Check each tool entry's quoting during validation A tool's command reaches the shell as one string. A quote that one entry leaves open pairs with a quote in a later entry, so the command's words shift. A typographic quote pasted from a web page is the usual cause, since a shell reads it as an ordinary character. The build then fails with an unrelated error such as `no input files`, or runs with corrupted paths. ToolValidator now checks :executable and every argument, hash arguments included, as each tool validates. ShellQuoting reads one entry as a shell does. A backslash escapes outside single quotes, and on Windows a single quote is ordinary. ToolQuoting walks a tool's entries and words the findings. An unclosed quote fails validation and names the entry, along with any typographic quote as its likely cause. A typographic quote in closed quoting only warns. An executable left unclosed skips the search for its file, so it reports once. Optional tools are checked too. Every built-in core and plugin tool passes with no finding, on Windows and elsewhere. Co-Authored-By: Claude Opus 5.5 --- lib/ceedling/tools/shell_quoting.rb | 45 ++++++++ lib/ceedling/tools/tool_quoting.rb | 79 +++++++++++++ lib/ceedling/tools/tool_validator.rb | 25 ++-- .../units/tools/default_tools_quoting_spec.rb | 40 ++++++- spec/units/tools/shell_quoting_spec.rb | 76 ++++++++++++ spec/units/tools/tool_validator_spec.rb | 109 ++++++++++++++++++ 6 files changed, 364 insertions(+), 10 deletions(-) create mode 100644 lib/ceedling/tools/shell_quoting.rb create mode 100644 lib/ceedling/tools/tool_quoting.rb create mode 100644 spec/units/tools/shell_quoting_spec.rb diff --git a/lib/ceedling/tools/shell_quoting.rb b/lib/ceedling/tools/shell_quoting.rb new file mode 100644 index 000000000..b2f8a1839 --- /dev/null +++ b/lib/ceedling/tools/shell_quoting.rb @@ -0,0 +1,45 @@ +# ========================================================================= +# Ceedling - Test-Centered Build System for C +# ThrowTheSwitch.org +# Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams +# SPDX-License-Identifier: MIT +# ========================================================================= + +require 'ceedling/constants' + +# Reads the quoting in one piece of a command line as the shell running it will. +# +# A tool's command reaches the shell as one string, so a quote one piece leaves open pairs +# with a quote in a later piece and the command's words shift. A typographic quote looks +# like a quote but is an ordinary character to every shell. +module ShellQuoting + + TYPOGRAPHIC = %w[“ ” „ ‟ ‘ ’ ‚ ‛ « » ‹ ›].freeze + + # Each alternative consumes one escaped character or one closed span, in that order, so a + # quote matched alone is one that never closes. A backslash escapes the character after + # it, except inside single quotes. + SPANS = /\\.|"(?:\\.|[^"\\])*"|'[^']*'|["']/m + + # cmd.exe treats a single quote as an ordinary character + WINDOWS_SPANS = /\\.|"(?:\\.|[^"\\])*"|"/m + + # The quote character `text` leaves open, or nil when every quote closes + def self.unclosed(text, windows:) + return scannable( text ).scan( windows ? WINDOWS_SPANS : SPANS ).find { |span| span == '"' or span == "'" } + end + + # The distinct typographic quotes in `text`, in the order they first appear + def self.typographic(text) + return scannable( text ).each_char.select { |char| TYPOGRAPHIC.include?( char ) }.uniq + end + + # `text` with invalid bytes replaced and everything from its first Ruby expansion through + # its last removed, since an expansion's own quotes are Ruby's, not the shell's. A quote + # between two expansions goes unread, so a mistake there is missed rather than invented. + def self.scannable(text) + return text.scrub.gsub( PATTERNS::RUBY_STRING_REPLACEMENT, '' ) + end + private_class_method :scannable + +end diff --git a/lib/ceedling/tools/tool_quoting.rb b/lib/ceedling/tools/tool_quoting.rb new file mode 100644 index 000000000..a10bb5864 --- /dev/null +++ b/lib/ceedling/tools/tool_quoting.rb @@ -0,0 +1,79 @@ +# ========================================================================= +# Ceedling - Test-Centered Build System for C +# ThrowTheSwitch.org +# Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams +# SPDX-License-Identifier: MIT +# ========================================================================= + +require 'ceedling/tools/shell_quoting' + +# Finds the quoting problems in a tool definition, one entry at a time. +# +# Each entry that reaches the shell must close its own quotes, since a quote left open pairs +# with one in a later entry. A typographic quote is only a warning, since it may be meant +# literally, as in a string a define holds. +module ToolQuoting + + # `error` is false for a warning + Finding = Struct.new( :field, :message, :error, keyword_init: true ) do + # An executable whose quote is unclosed names no file that can be looked for + def unclosed_executable? + return (error and field == :executable) + end + end + + # The findings for `tool`'s :executable and arguments, in order + def self.findings(tool, name:, windows:) + return entries( tool ).filter_map { |field, text| finding( name, field, text, windows ) } + end + + # Each [field, text] pair the command line is built from + def self.entries(tool) + arguments = [tool[:arguments]].flatten.flat_map { |element| expanded( element ) } + entries = [[:executable, tool[:executable]]] + arguments.map { |argument| [:arguments, argument] } + + return entries.select { |_, text| text.is_a?( String ) } + end + + # The text one argument contributes, as ToolExecutor expands it. A string is itself the + # text. A hash contributes its first key, the substitution string, and each string among + # that key's values. Anything else adds nothing to the command line. + def self.expanded(element) + return [element] if element.is_a?( String ) + return [] unless element.is_a?( Hash ) and element.any? + + substitution, values = element.first + return [substitution.to_s, *[values].flatten.grep( String )] + end + + def self.finding(name, field, text, windows) + location = "#{name} ↳ :#{field} ➡️ `#{text}`" + quote = ShellQuoting.unclosed( text, windows: windows ) + typographic = ShellQuoting.typographic( text ) + + return unclosed( location, field, quote, typographic ) if quote + return nil if typographic.empty? + + message = "#{location} holds #{phrase( typographic )} Use \" or ' unless the characters are meant literally." + return Finding.new( field: field, message: message, error: false ) + end + + # An unclosed quote's error names any typographic quote as its likely cause + def self.unclosed(location, field, quote, typographic) + subject = (field == :executable) ? 'executable' : 'argument' + message = "#{location} leaves a #{quote} quote unclosed. Enclose the #{subject} with #{quote} quotes." + message += " It holds #{phrase( typographic )} Replace it with #{quote}." if typographic.any? + + return Finding.new( field: field, message: message, error: true ) + end + + # The typographic quotes found, and what a shell makes of them + def self.phrase(typographic) + return "#{typographic.first}, a typographic quote that a shell treats as an ordinary character." if typographic.one? + + return "#{typographic.join( ' ' )}, typographic quotes that a shell treats as ordinary characters." + end + + private_class_method :entries, :expanded, :finding, :unclosed, :phrase + +end diff --git a/lib/ceedling/tools/tool_validator.rb b/lib/ceedling/tools/tool_validator.rb index 7e7dcd8c5..8715656e9 100644 --- a/lib/ceedling/tools/tool_validator.rb +++ b/lib/ceedling/tools/tool_validator.rb @@ -9,13 +9,15 @@ require 'ceedling/constants' require 'ceedling/filename_extension' require 'ceedling/exceptions' +require 'ceedling/tools/tool_quoting' # Confirms a tool's configuration can run before a build depends on it. # -# A tool is valid when its executable can be found and its stderr redirect is a known -# option. The executable is an explicit path or a bare name searched on PATH, and either -# may omit the extension its file carries on disk. An executable built at run time, from -# an argument or a Ruby expansion, is left for the shell to resolve. +# A tool is valid when its executable and each argument close the quotes they open, its +# executable can be found and its stderr redirect is a known option. The executable is an +# explicit path or a bare name searched on PATH, and either may omit the extension its file +# carries on disk. An executable built at run time, from an argument or a Ruby expansion, +# is left for the shell to resolve. class ToolValidator constructor :file_wrapper, :loginator, :system_wrapper, :ruby_expandinator @@ -63,9 +65,11 @@ def validate(tool:, name:nil, extension:nil, respect_optional:false, boom:false) name = tool[:name] if name.nil? or name.empty? extension ||= default_extension() - valid = validate_executable( tool:tool, name:name, extension:extension, respect_optional:respect_optional, boom:boom ) - - # Both checks run, so a tool with two problems reports both + # Every check runs, so a tool with several problems reports each. An executable whose + # quote is unclosed can't be found, and saying so would only repeat the quoting error. + findings = ToolQuoting.findings( tool, name:name, windows:@system_wrapper.windows? ) + valid = validate_quoting( findings, boom ) + valid &= validate_executable( tool:tool, name:name, extension:extension, respect_optional:respect_optional, boom:boom ) unless findings.any?( &:unclosed_executable? ) return valid & validate_stderr_redirect( tool:tool, name:name, boom:boom ) end @@ -73,6 +77,13 @@ def validate(tool:, name:nil, extension:nil, respect_optional:false, boom:false) private + # An unclosed quote fails validation, and a typographic quote only warns + def validate_quoting(findings, boom) + findings.reject( &:error ).each { |finding| @loginator.log( finding.message, Verbosity::COMPLAIN ) } + + return findings.select( &:error ).map { |finding| fail_validation( finding.message, boom ) }.all? + end + def validate_executable(tool:, name:, extension:, respect_optional:, boom:) command = tool[:executable] executable = ToolValidator.executable_from( command ) diff --git a/spec/units/tools/default_tools_quoting_spec.rb b/spec/units/tools/default_tools_quoting_spec.rb index dd3aaa638..37bcb7136 100644 --- a/spec/units/tools/default_tools_quoting_spec.rb +++ b/spec/units/tools/default_tools_quoting_spec.rb @@ -12,9 +12,10 @@ require 'ceedling/tools/tool_executor' require 'ceedling/ruby_expandinator' -load File.expand_path( '../../../plugins/gcov/config/defaults_gcov.rb', __dir__ ) -load File.expand_path( '../../../plugins/bullseye/config/defaults_bullseye.rb', __dir__ ) -load File.expand_path( '../../../plugins/cppcheck/config/defaults_cppcheck.rb', __dir__ ) +require 'ceedling/tools/tool_validator' +require 'ceedling/filename_extension' + +Dir[File.expand_path( '../../../plugins/*/config/defaults_*.rb', __dir__ )].each { |defaults| load defaults } # GH #1373: the default tools that run a test executable named it unquoted, so a path holding # an apostrophe or a space broke the shell command. Each command here is split as a POSIX @@ -81,3 +82,36 @@ def words(tool, *args) expect( words( DEPENDENCIES_TOOLS[:deps_zip], 'vendor/my dir/x.zip' ) ).to eq( ['unzip', '-o', 'vendor/my dir/x.zip'] ) end end + +# Tool validation checks every tool's quoting on every build, Ceedling's own tools included, +# so none of them may draw an error or a warning on any platform +describe 'Default tools quoting validation' do + # Every tool Ceedling and its plugins define: each constant holding one, and each tool in + # a plugin's YAML defaults + BUILT_IN_TOOLS = ( + Object.constants.grep( /\ADEFAULT_\w+_TOOL\z/ ).map { |name| [name.to_s, Object.const_get( name )] } + + Dir[File.expand_path( '../../../plugins/*/config/*.yml', __dir__ )].flat_map do |filepath| + tools = YAML.load_file( filepath, symbolize_names: true )&.dig( :tools ) || {} + tools.map { |key, tool| ["#{File.basename( File.dirname( filepath, 2 ) )} :#{key}", tool] } + end + ).freeze + + [false, true].each do |windows| + it "finds every built-in tool's quoting closed and straight #{windows ? 'on' : 'off'} Windows" do + loginator = double( 'loginator' ) + system_wrapper = double( 'system_wrapper', windows?: windows, search_paths: ['/bin'] ) + file_wrapper = double( 'file_wrapper', exist?: true ) + validator = ToolValidator.new( file_wrapper: file_wrapper, loginator: loginator, system_wrapper: system_wrapper, ruby_expandinator: RubyExpandinator.new ) + + complaints = [] + allow( loginator ).to receive( :log ) { |message, *| complaints << message } + + # 50 core and plugin tools, so a narrowed collection fails here, not silently + expect( BUILT_IN_TOOLS.size ).to be >= 50 + BUILT_IN_TOOLS.each do |name, tool| + expect( validator.validate( tool: Marshal.load( Marshal.dump( tool ) ), name: name, extension: FilenameExtension.new( '' ) ) ).to be( true ), name + end + expect( complaints ).to eq( [] ) + end + end +end diff --git a/spec/units/tools/shell_quoting_spec.rb b/spec/units/tools/shell_quoting_spec.rb new file mode 100644 index 000000000..c378a01ec --- /dev/null +++ b/spec/units/tools/shell_quoting_spec.rb @@ -0,0 +1,76 @@ +# ========================================================================= +# Ceedling - Test-Centered Build System for C +# ThrowTheSwitch.org +# Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams +# SPDX-License-Identifier: MIT +# ========================================================================= + +require 'spec_helper' +require 'ceedling/tools/shell_quoting' + +describe ShellQuoting do + describe '.unclosed' do + # The last case is two mistakes that balance once joined, which is why a tool's entries + # are each read on their own + { + 'no quotes' => '-g', + 'a closed double-quoted span' => '-I"${5}"', + 'a closed single-quoted span' => "-DNAME='a b'", + 'an escaped quote inside double quotes' => '-D"GREETING=\"hi\""', + 'an escaped quote outside quotes' => '-DQ=\"', + 'a single quote inside double quotes' => %q{-I"o'neil"}, + 'a double quote inside single quotes' => %q{-D'Q="'}, + 'an escaped replacement operator' => '"\${1}"', + "a Ruby expansion's own quotes" => %q{#{ENV['CC_FLAGS']} -c}, + 'an even count of mismatched quotes' => "-I\"a\u201d -I\"b\u201d" + }.each do |description, text| + it "finds nothing open in #{description}" do + expect( ShellQuoting.unclosed( text, windows: false ) ).to be_nil + end + end + + { + 'an unclosed double quote' => ['-I"src', '"'], + 'an unclosed single quote' => ["-DNAME='a", "'"], + 'a backslash before the closing quote' => ['-I"C:\\inc\\"', '"'], + "a straight quote closed by a typographic one" => ["-I\"${5}\u201d", '"'] + }.each do |description, (text, open)| + it "finds #{open} open in #{description}" do + expect( ShellQuoting.unclosed( text, windows: false ) ).to eq( open ) + end + end + + # cmd.exe reads a single quote as an ordinary character + it 'ignores a single quote on Windows' do + expect( ShellQuoting.unclosed( "C:/Users/O'Brien/cc", windows: true ) ).to be_nil + end + + it 'still finds an unclosed double quote on Windows' do + expect( ShellQuoting.unclosed( %q{-I"o'neil}, windows: true ) ).to eq( '"' ) + end + + it 'reads text holding invalid bytes' do + expect( ShellQuoting.unclosed( "-I\"\xFF", windows: false ) ).to eq( '"' ) + end + end + + describe '.typographic' do + ShellQuoting::TYPOGRAPHIC.each do |quote| + it "finds #{quote}" do + expect( ShellQuoting.typographic( "-I#{quote}src#{quote}" ) ).to eq( [quote] ) + end + end + + it 'lists each distinct quote once, in order of appearance' do + expect( ShellQuoting.typographic( "\u201ca\u201d \u201cb\u201d" ) ).to eq( ["\u201c", "\u201d"] ) + end + + it 'finds none in straight quoting' do + expect( ShellQuoting.typographic( %q{-I"a" -D'b'} ) ).to eq( [] ) + end + + it 'reads text holding invalid bytes' do + expect( ShellQuoting.typographic( "\xFF\u201d" ) ).to eq( ["\u201d"] ) + end + end +end diff --git a/spec/units/tools/tool_validator_spec.rb b/spec/units/tools/tool_validator_spec.rb index f2021d82a..0486ef0ee 100644 --- a/spec/units/tools/tool_validator_spec.rb +++ b/spec/units/tools/tool_validator_spec.rb @@ -336,4 +336,113 @@ def candidates(executable, extension: FilenameExtension.new(['.sh']), windows: f expect( validate( tool('gcc') ) ).to be(true) end end + + # Which quotes open and close is ShellQuoting's to decide, and its spec covers the rules. + # Here, which entries are checked and what each finding does. + describe 'quoting' do + before(:each) { exists( '/usr/bin/gcc' ) } + + # A typographic quote ends an otherwise straight-quoted path, as copied from a web page + let(:pasted) { "-I\"${5}”" } + + it 'logs an unclosed quote in an argument and returns false' do + expect(@loginator).to receive(:log).with( + "my_tool ↳ :arguments ➡️ `-I\"src` leaves a \" quote unclosed. Enclose the argument with \" quotes.", Verbosity::ERRORS + ) + expect( validate( tool('gcc', :arguments => ['-g', '-I"src']) ) ).to be(false) + end + + it 'raises on an unclosed quote under boom' do + expect { validate( tool('gcc', :arguments => ['-I"src']), boom: true ) }.to raise_error(CeedlingException, /leaves a " quote unclosed/) + end + + it 'names a typographic quote as the likely cause of an unclosed one' do + expect(@loginator).to receive(:log).with( + "my_tool ↳ :arguments ➡️ `#{pasted}` leaves a \" quote unclosed. Enclose the argument with \" quotes. " \ + "It holds ”, a typographic quote that a shell treats as an ordinary character. Replace it with \".", Verbosity::ERRORS + ) + validate( tool('gcc', :arguments => [pasted]) ) + end + + # Closing quotes here would pair with an opening one in the next entry + it 'checks each argument on its own' do + expect( validate( tool('gcc', :arguments => ['-DMSG="a', 'b"']) ) ).to be(false) + end + + it 'warns on a typographic quote in closed quoting and leaves the tool valid' do + expect(@loginator).to receive(:log).with( + "my_tool ↳ :arguments ➡️ `-D“x”` holds “ ”, typographic quotes that a shell treats as ordinary characters. " \ + "Use \" or ' unless the characters are meant literally.", Verbosity::COMPLAIN + ) + expect( validate( tool('gcc', :arguments => ["-D“x”"]) ) ).to be(true) + end + + it "checks a hash argument's substitution string and values" do + expect( validate( tool('gcc', :arguments => [{ pasted => 'COLLECTION_PATHS' }]) ) ).to be(false) + expect( validate( tool('gcc', :arguments => [{ '-I"$"' => ['a', ['-D"b']] }]) ) ).to be(false) + end + + it 'checks a substitution string given as a symbol' do + expect( validate( tool('gcc', :arguments => [{ :'-I"$' => 'COLLECTION_PATHS' }]) ) ).to be(false) + end + + # ToolExecutor expands only a hash's first key, and only strings among its values + it 'checks only what a hash argument adds to the command line' do + expect( validate( tool('gcc', :arguments => [{ '-I"$"' => ['a', 8], '-D"b' => 'c' }]) ) ).to be(true) + end + + # ToolExecutor drops an argument that is neither a string nor a hash + it 'skips a symbol argument' do + expect( validate( tool('gcc', :arguments => [:'-I"src']) ) ).to be(true) + end + + it "reads past a Ruby expansion's own quotes" do + expect( validate( tool('gcc', :arguments => ['-D"NAME=#{ENV[\'USER\']}"']) ) ).to be(true) + end + + it 'warns on a typographic quote in :executable and still looks for its file' do + expect(@loginator).to receive(:log).with(/:executable ➡️ `“cc”` holds “ ”/, Verbosity::COMPLAIN) + expect(@loginator).to receive(:log).with(/`“cc”` does not exist/, Verbosity::ERRORS) + expect( validate( tool("“cc”") ) ).to be(false) + end + + it 'logs the warnings for a tool before raising on its error under boom' do + expect(@loginator).to receive(:log).with(/holds ”/, Verbosity::COMPLAIN) + expect { validate( tool('gcc', :arguments => ["-D\"x”\"", '-I"src']), boom: true ) }.to raise_error(CeedlingException, /`-I"src`/) + end + + it 'checks an argument inside a nested list, as a YAML alias makes' do + expect( validate( tool('gcc', :arguments => [['-g', ['-I"src']]]) ) ).to be(false) + end + + it 'checks an optional tool' do + expect( validate( tool('gcc', :optional => true, :arguments => ['-I"src']), respect_optional: true ) ).to be(false) + end + + it 'reports an unclosed executable once, without looking for its file' do + expect(@file_wrapper).to_not receive(:exist?) + expect(@loginator).to receive(:log).once.with( + "my_tool ↳ :executable ➡️ `\"Code Cruncher”` leaves a \" quote unclosed. Enclose the executable with \" quotes. " \ + "It holds ”, a typographic quote that a shell treats as an ordinary character. Replace it with \".", Verbosity::ERRORS + ) + expect( validate( tool("\"Code Cruncher”") ) ).to be(false) + end + + it 'reports every unclosed entry, and the other checks too' do + expect(@loginator).to receive(:log).with(/:arguments ➡️ `-I"a`/, Verbosity::ERRORS) + expect(@loginator).to receive(:log).with(/:arguments ➡️ `-I"b`/, Verbosity::ERRORS) + expect(@loginator).to receive(:log).with(/:stderr_redirect/, Verbosity::ERRORS) + validate( tool('gcc', :arguments => ['-I"a', '-I"b'], :stderr_redirect => :bogus) ) + end + + it 'reads a single quote as an ordinary character on Windows' do + allow(@system_wrapper).to receive(:windows?).and_return(true) + exists( '/usr/bin/gcc.exe' ) + expect( validate( tool('gcc', :arguments => ["-IC:/Users/O'Brien"]) ) ).to be(true) + end + + it 'passes arguments that are not strings' do + expect( validate( tool('gcc', :arguments => [8, nil]) ) ).to be(true) + end + end end From 7d3ccb8a9770ec5adc1eadf36bd25ddd31ad10f9 Mon Sep 17 00:00:00 2001 From: Michael Karlesky Date: Fri, 13 Nov 2026 00:09:01 -0500 Subject: [PATCH 3/4] Document the tool quoting check The tools reference notes that each argument closes its own quotes and that a typographic quote draws a warning. The Changelog lists the check under 1.2.3's additions. Breaking Changes describes a quote that spans two arguments, which now fails validation. Co-Authored-By: Claude Opus 5.5 --- docs/BreakingChanges.md | 8 ++++++++ docs/Changelog.md | 1 + docs/mkdocs/configuration/reference/tools.md | 8 ++++++++ 3 files changed, 17 insertions(+) diff --git a/docs/BreakingChanges.md b/docs/BreakingChanges.md index 96586850c..854554305 100644 --- a/docs/BreakingChanges.md +++ b/docs/BreakingChanges.md @@ -10,6 +10,14 @@ A release has a section only if it breaks something. Each section lists what cha --- +# [1.2.3] — Unreleased + +## Each tool argument closes its own quotes + +Tool validation now fails a tool whose `:executable` or argument leaves a quote open ([tool definitions](https://docs.throwtheswitch.org/Ceedling/1.2.0/configuration/reference/tools/#tool-definition-configurable-elements)). A tool that opens a quote in one `:arguments` entry and closes it in a later one worked before and now fails. Join such entries into one, as in `- -DMSG="a b"` in place of `- -DMSG="a` and `- b"`. + +--- + # [1.2.2] — 2026-10-31 ## Test build output is organized by each test’s path from the project root diff --git a/docs/Changelog.md b/docs/Changelog.md index 2d0243fc8..9ec737e93 100644 --- a/docs/Changelog.md +++ b/docs/Changelog.md @@ -48,6 +48,7 @@ Each release has its own section, listing only what changed in that release. ## 🌟 Added - More and better guidance on compilation and linking failures that point to common root causes. More cases are covered with more complete explanations and consistent wording. Failure matching is expanded to help across a variety of toolchains. A test whose Partials macro, such as `PARTIAL_LOCAL_VAR()`, builds a name nothing declares gets guidance on the macro’s arguments. +- [#699](https://github.com/ThrowTheSwitch/Ceedling/issues/699) Added a check of each tool’s quoting when Ceedling validates its configuration ([tool definitions](https://docs.throwtheswitch.org/Ceedling/1.2.0/configuration/reference/tools/#tool-definition-configurable-elements)). A quote that `:executable` or an argument leaves open fails validation and names the entry. A typographic quote such as `”`, often pasted from a web page, draws a warning, and it is named as the likely cause of a quote left open. Before, a quote left open paired with one in a later argument. The build then failed with an unrelated error, such as `no input files`, or ran with corrupted paths. - Added `PARTIAL_TYPE()` and `PARTIAL_LOCAL_TYPE()` to `ceedling.h`. Each names the type a [Partial](https://docs.throwtheswitch.org/Ceedling/1.2.0/testing-guide/partials/) gives a variable declared together with its type, so a test can declare another object of that type, such as a saved copy of a module’s state ([Partials macros](https://docs.throwtheswitch.org/Ceedling/1.2.0/reference/partials-macros/#variable-type-names)). - [#1386](https://github.com/ThrowTheSwitch/Ceedling/issues/1386) Added [`:project` ↳ `:win_path_limit`](https://docs.throwtheswitch.org/Ceedling/1.2.0/configuration/reference/project/#win_path_limit) for Windows. `:classic`, the default, keeps Windows’ 260-character limit and now also flags a directory Ceedling creates past 248 characters. `:long_paths` and `:auto` stop long path logging warnings/errors on a host with long paths enabled, after checking once that Ruby can work with long paths. If that check fails, the new optional [`:windows_registry_query`](https://docs.throwtheswitch.org/Ceedling/1.2.0/configuration/reference/tools/#windows_registry_query) tool reads the host’s registry setting to name the cause. On Ruby before 4.0, which can create long paths but not list them, `:auto` keeps the classic limit, and `:long_paths` warns once about what can fail. The setting changes only what Ceedling reports. - Added [`:partials` ↳ `:suppress_redundant_decls`](https://docs.throwtheswitch.org/Ceedling/1.2.0/configuration/reference/partials/#suppress_redundant_decls). Enabled by default, it wraps the prototypes a [Partial](https://docs.throwtheswitch.org/Ceedling/1.2.0/testing-guide/partials/) carries in GCC diagnostic pragmas, so `-Wredundant-decls` stays quiet where a carried prototype repeats a header’s declaration. diff --git a/docs/mkdocs/configuration/reference/tools.md b/docs/mkdocs/configuration/reference/tools.md index ad4006aff..57bb4fd16 100644 --- a/docs/mkdocs/configuration/reference/tools.md +++ b/docs/mkdocs/configuration/reference/tools.md @@ -236,6 +236,14 @@ line such as `LongPathsEnabled REG_DWORD 0x1` in its output. characters. On Linux and macOS, a path holding `"`, `$`, a backtick, or `\` can still break a command. + !!! note "Each argument closes its own quotes" + Ceedling checks the quoting in `:executable` and in each argument when it + validates a tool. A quote left open fails validation. Every argument must + close quotes it opens; a quoted value can’t span two entries in the list. + A typographic quote (e.g. `”`) pasted from elsewhere draws a warning. A + shell treats it as an ordinary character. On Windows, `'` is an ordinary + character too and is not checked. + 1. `:name` - Simple name (i.e. "nickname") of tool beyond its executable name. This is optional. If not explicitly set then Ceedling will form a name from the tool’s YAML entry key. From 2bf5de7c0121d92a3a22f7c79f2a82d475f8e070 Mon Sep 17 00:00:00 2001 From: Michael Karlesky Date: Fri, 13 Nov 2026 07:38:27 -0500 Subject: [PATCH 4/4] Name plugin tools without Ruby 3.1's File.dirname level The quoting guard spec labeled each plugin YAML tool with File.dirname( path, 2 ). The level argument arrived in Ruby 3.1, so the spec failed to load on the Ruby 3.0 CI jobs. Nested dirname calls give the same label on every supported Ruby. Co-Authored-By: Claude Opus 5.5 --- spec/units/tools/default_tools_quoting_spec.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/units/tools/default_tools_quoting_spec.rb b/spec/units/tools/default_tools_quoting_spec.rb index 37bcb7136..d48396078 100644 --- a/spec/units/tools/default_tools_quoting_spec.rb +++ b/spec/units/tools/default_tools_quoting_spec.rb @@ -92,7 +92,7 @@ def words(tool, *args) Object.constants.grep( /\ADEFAULT_\w+_TOOL\z/ ).map { |name| [name.to_s, Object.const_get( name )] } + Dir[File.expand_path( '../../../plugins/*/config/*.yml', __dir__ )].flat_map do |filepath| tools = YAML.load_file( filepath, symbolize_names: true )&.dig( :tools ) || {} - tools.map { |key, tool| ["#{File.basename( File.dirname( filepath, 2 ) )} :#{key}", tool] } + tools.map { |key, tool| ["#{File.basename( File.dirname( File.dirname( filepath ) ) )} :#{key}", tool] } end ).freeze