From f0cf515acc1110e91327b1ee6112bbd7fbcf6120 Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Wed, 20 May 2026 15:22:26 +0200 Subject: [PATCH 1/4] Remove `analyze` mode. --- README.md | 9 +---- analyzing/analyzing.go | 88 ------------------------------------------ cli/cli.go | 13 +------ cli/cli_test.go | 1 - cli/cli_validation.go | 8 ++-- main.go | 12 ++---- 6 files changed, 11 insertions(+), 120 deletions(-) delete mode 100644 analyzing/analyzing.go diff --git a/README.md b/README.md index bac9e26..9b6436c 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ For the details of the usage in the documentation and the code, please refer to ## Running -Embed Code operates in three modes: +Embed Code operates in two modes: 1. **Embedding**: Scans documentation files for `` tags and performs the requested embeddings, overwriting the content of the target documentation files. @@ -26,14 +26,9 @@ Embed Code operates in three modes: 2. **Up-to-Date Check**: Compares the content under `` tags with the corresponding source code fragments. If they differ, the tool reports which files are out-of-date. -3. **Analysis**: Verifies that all embeddings have matching source code fragments. - Any issues are logged to `build/analytics/problem-files.txt`. - - The mode is selected using the mandatory `-mode` argument: - `embed`: Performs the embedding process. - `check`: Checks if embeddings are up-to-date. -- `analyze`: Runs the analysis process. The tool can be run as a pre-compiled binary or via the Go compiler (requires Go [installed](#installation)). Binaries are located in the `./bin` directory. @@ -60,7 +55,7 @@ go run ./main.go [arguments] ### Arguments The available arguments are: - * `-mode`: (Mandatory) The execution mode: `embed`, `check`, or `analyze`. + * `-mode`: (Mandatory) The execution mode: `embed` or `check`. * `-code-path`: (Optional) Path to the source code root directory. * `-docs-path`: (Optional) Path to the documentation root directory. * `-config-path`: (Optional) Path to a YAML configuration file containing `code-path` and `docs-path`. diff --git a/analyzing/analyzing.go b/analyzing/analyzing.go deleted file mode 100644 index 904fe10..0000000 --- a/analyzing/analyzing.go +++ /dev/null @@ -1,88 +0,0 @@ -package analyzing - -import ( - "fmt" - "os" - "path/filepath" - - "embed-code/embed-code-go/configuration" - "embed-code/embed-code-go/embedding" - "embed-code/embed-code-go/files" - - "github.com/bmatcuk/doublestar/v4" -) - -const ( - analyticsDir = "./build/analytics" - embeddingsNotFoundFile = "embeddings-not-found-files.txt" - embeddingChangedFile = "embeddings-changed-files.txt" - // Represents read and write permissions for the owner of the file, and read-only permissions - // for group and others. - permission = 0755 -) - -// AnalyzeAll analyzes all documentation files. If any error occurs during embedding, it is written -// to the analytics file with all the needed information. -// -// config — a configuration for embedding. -func AnalyzeAll(config configuration.Configuration) { - docFiles := findDocumentationFiles(config) - changedEmbeddings, problemEmbeddings := extractAnalyticsForDocs(config, docFiles) - - if err := os.MkdirAll(analyticsDir, permission); err != nil { - panic(err) - } - files.WriteLinesToFile(pathToFile(embeddingChangedFile), changedEmbeddings) - files.WriteLinesToFile(pathToFile(embeddingsNotFoundFile), problemEmbeddings) -} - -// Generates a path to a given file in the analytics directory. -func pathToFile(fileName string) string { - return filepath.Join(analyticsDir, fileName) -} - -// Finds all documentation files for given config. -func findDocumentationFiles(config configuration.Configuration) []string { - documentationRoot := config.DocumentationRoot - docPatterns := config.DocIncludes - var documentationFiles []string - for _, pattern := range docPatterns { - globString := filepath.Join(documentationRoot, filepath.FromSlash(pattern)) - matches, err := doublestar.FilepathGlob(globString) - if err != nil { - panic(err) - } - for _, match := range matches { - documentationFiles = append(documentationFiles, filepath.ToSlash(match)) - } - } - - return documentationFiles -} - -// Returns a list of embeddings that are not up-to-date with their code files. -// Also returns a list of embeddings which cause an error. -func extractAnalyticsForDocs( - config configuration.Configuration, docFiles []string) ([]string, []string) { - var changedEmbeddingsLines, problemEmbeddingsLines []string - - for _, docFile := range docFiles { - processor := embedding.NewProcessor(docFile, config) - changedEmbeddings, err := processor.FindChangedEmbeddings() - - // If there is an error during embedding, it is written to the analytics file. - if err != nil { - problemEmbeddingsLines = append(problemEmbeddingsLines, err.Error()) - } - // Even if error occurs, there might be embeddings that are changed. - if len(changedEmbeddings) > 0 { - docRelPath := files.BuildDocRelativePath(docFile, config) - for _, changedEmbedding := range changedEmbeddings { - line := fmt.Sprintf("%s : %s", docRelPath, changedEmbedding.String()) - changedEmbeddingsLines = append(changedEmbeddingsLines, line) - } - } - } - - return changedEmbeddingsLines, problemEmbeddingsLines -} diff --git a/cli/cli.go b/cli/cli.go index ac46d41..75b7e83 100644 --- a/cli/cli.go +++ b/cli/cli.go @@ -24,7 +24,6 @@ import ( "os" "strings" - "embed-code/embed-code-go/analyzing" "embed-code/embed-code-go/configuration" "embed-code/embed-code-go/embedding" @@ -90,9 +89,8 @@ type EmbedCodeSamplesResult struct { } const ( - ModeCheck = "check" - ModeEmbed = "embed" - ModeAnalyze = "analyze" + ModeCheck = "check" + ModeEmbed = "embed" ) // CheckCodeSamples returns documentation files that are not up-to-date with code files. @@ -112,13 +110,6 @@ func EmbedCodeSamples(config configuration.Configuration) EmbedCodeSamplesResult } } -// AnalyzeCodeSamples analyzes code fragments in documentation files. -// -// config — a configuration for embedding. -func AnalyzeCodeSamples(config configuration.Configuration) { - analyzing.AnalyzeAll(config) -} - // ReadArgs reads user-specified args from the command line. // // Returns Config struct filled with the corresponding args. diff --git a/cli/cli_test.go b/cli/cli_test.go index 0d123a2..4a9de17 100644 --- a/cli/cli_test.go +++ b/cli/cli_test.go @@ -52,7 +52,6 @@ var _ = Describe("CLI validation", func() { }, Entry("with check mode", cli.ModeCheck), - Entry("with analyze mode", cli.ModeAnalyze), Entry("with embed mode", cli.ModeEmbed), ) diff --git a/cli/cli_validation.go b/cli/cli_validation.go index 5b8bd8c..6220bb0 100644 --- a/cli/cli_validation.go +++ b/cli/cli_validation.go @@ -82,19 +82,19 @@ func ValidateConfigFile(userConfig Config) error { return errors.New("expected to use config file, but it does not exist") } -// validateMode checks if mode is set to check, embed, or analyze. +// validateMode checks if mode is set to check or embed. func validateMode(mode string) error { isModeSet := isNotEmpty(mode) if !isModeSet { return errors.New("mode must be set") } - validModes := []string{ModeEmbed, ModeAnalyze, ModeCheck} + validModes := []string{ModeEmbed, ModeCheck} isValidMode := slices.Contains(validModes, mode) if !isValidMode { - return fmt.Errorf("invalid value for mode. it must be one of — `%s`, `%s` or `%s`", - ModeEmbed, ModeCheck, ModeAnalyze) + return fmt.Errorf("invalid value for mode. it must be one of — `%s` or `%s`", + ModeEmbed, ModeCheck) } return nil diff --git a/main.go b/main.go index f742bbd..8af8d82 100644 --- a/main.go +++ b/main.go @@ -32,9 +32,9 @@ const Version = "1.2.0" // The entry point for embed-code. // -// There are three modes, which are chosen by 'mode' arg. If it is set to 'check', +// There are two modes, which are chosen by 'mode' arg. If it is set to 'check', // then the checking for up-to-date is performed. If it is set to 'embed', the embedding is -// performed. If it is set to 'analyze', the analyzing is performed. +// performed. // // EmbeddingInstruction is the process that consists of the following steps: // - the code fragments are extracted from the code files; @@ -65,10 +65,9 @@ const Version = "1.2.0" // - code-path — a path to a root directory with code files; // - docs-path — a path to a root directory with docs files; // - config-path — a path to a yaml configuration file; -// - mode — string which represents the mode of embed-code execution. if it is set to 'check', +// - mode — string which represents the mode of embed-code execution. If it is set to 'check', // then the checking for up-to-date is performed. If it is set to 'embed', the embedding // is performed. -// If it is set to 'analyze', the analyzing is performed; // - doc-includes — a comma-separated string of glob patterns for docs files to include. // For example: // "docs/**/*.md,guides/*.html". Default value is "**/*.md,**/*.html"; @@ -112,11 +111,6 @@ func main() { case cli.ModeEmbed: embedByConfigs(configs) fmt.Println("Embedding process finished.") - case cli.ModeAnalyze: - for _, config := range configs { - cli.AnalyzeCodeSamples(config) - } - fmt.Println("Analysis is completed, analytics files can be found in /build/analytics folder.") } } From 76811c284a5017f54a9cf83e571543ee55717272 Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Wed, 20 May 2026 15:43:08 +0200 Subject: [PATCH 2/4] Improve doc. --- main.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/main.go b/main.go index 8af8d82..b08fad5 100644 --- a/main.go +++ b/main.go @@ -33,8 +33,8 @@ const Version = "1.2.0" // The entry point for embed-code. // // There are two modes, which are chosen by 'mode' arg. If it is set to 'check', -// then the checking for up-to-date is performed. If it is set to 'embed', the embedding is -// performed. +// then the checking for up-to-date is performed. If it is set to 'embed', +// the embedding is performed. // // EmbeddingInstruction is the process that consists of the following steps: // - the code fragments are extracted from the code files; From 774060e3cf891ee2c2af7fe17242e47fd6bb4abc Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Wed, 20 May 2026 16:26:59 +0200 Subject: [PATCH 3/4] Fix quotes. --- embedding/commentfilter/visual_basic.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/embedding/commentfilter/visual_basic.go b/embedding/commentfilter/visual_basic.go index 645d61c..7e31cc5 100644 --- a/embedding/commentfilter/visual_basic.go +++ b/embedding/commentfilter/visual_basic.go @@ -30,7 +30,7 @@ const ( ) // VisualBasicCommentFilter filters the Visual Basic comment forms: -// - documentation comments starting with `”'`; +// - documentation comments starting with `'''`; // - apostrophe comments starting with `'`; // - REM comments starting with `REM`. type VisualBasicCommentFilter struct{} From 629b7df62245d7be3b19d5731e1150e7302278bc Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Wed, 20 May 2026 16:41:08 +0200 Subject: [PATCH 4/4] Fix unsupported mode behaviour. --- embedding/commentfilter/filter.go | 10 +++++++--- embedding/commentfilter/filter_test.go | 10 ++++++++++ 2 files changed, 17 insertions(+), 3 deletions(-) diff --git a/embedding/commentfilter/filter.go b/embedding/commentfilter/filter.go index 39544db..0356917 100644 --- a/embedding/commentfilter/filter.go +++ b/embedding/commentfilter/filter.go @@ -80,7 +80,9 @@ func filterFor( warnUnsupportedFileType(filePath, mode, embeddingDocPath, embeddingLine) return nil, false } - warnUnsupportedCommentsMode(filePath, mode, embeddingDocPath, embeddingLine, entry.supportedModes) + if warnUnsupportedCommentsMode(filePath, mode, embeddingDocPath, embeddingLine, entry.supportedModes) { + return nil, false + } return entry.filter, true } @@ -123,9 +125,9 @@ func warnUnsupportedCommentsMode( embeddingDocPath string, embeddingLine int, supportedModes []Mode, -) { +) bool { if containsMode(supportedModes, mode) { - return + return false } var wrappedModes []string for _, mode := range supportedModes { @@ -142,6 +144,8 @@ func warnUnsupportedCommentsMode( strings.Join(wrappedModes, ", "), ), ) + + return true } // fileURL returns an absolute file URL for a local path and line. diff --git a/embedding/commentfilter/filter_test.go b/embedding/commentfilter/filter_test.go index b2c0638..f33c630 100644 --- a/embedding/commentfilter/filter_test.go +++ b/embedding/commentfilter/filter_test.go @@ -451,6 +451,16 @@ var _ = Describe("Comment filter", func() { Expect(output).Should(ContainSubstring("guide.md:12")) Expect(output).Should(ContainSubstring("does not have a distinct meaning")) }) + + It("should leave content unchanged when mode is not supported for file type", func() { + lines := []string{ + "", + " ", + "", + } + + assertFiltered("layout.xml", RetainDocumentation, lines, lines) + }) }) })