documinty 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bcd92454896ed0ffc0ab3f3e86a064d71a62e2da5430fa1b7920aecac854ce6b
-  data.tar.gz: 740b56dd5581065c39d6cc09ff67c420867803d47c5420a5dfd4f8c682474616
+  metadata.gz: de1f0a6fded0793fb156e8111a074c44dda251836475980441b0c47576660147
+  data.tar.gz: 4fbb5cd7db1b97866eed50050754af3ac09998e7ff4486b5330adfd822fc1537
 SHA512:
-  metadata.gz: 47a1af0117416167328b171df5a3869adf2847f928a4d76f9a6c4c0c99661650929a42ded453e970760d1cee05d9bb1c8d22eeec65e48725e393865a24d73351
-  data.tar.gz: abdf028bb0da059b527b81198e4d7c00a6cc7fb71a4e6f31c5a97abecf059f69a4cb40216a8336377abc4650478f8270fc20bd96af8642defa8fc923b5d84aea
+  metadata.gz: f883d81566c6ab6013c5d6edbc77faf7b2661bb95ada107c1816787099ebc13e3dc92a246b36dbf1489620eed465e8da1c3e68896cd8d6a50224e93f6f9d4e7f
+  data.tar.gz: da024a6231ee1b7bbe131cf4393f5a20351ec7d8ae9e48655cd6ddfd9b8c89d3b0cf749af341970b666ff471704292ba79e904f974dbf4d5cceb67da54f00c98

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2025 TODO: Write your name
+Copyright (c) 2025 Marcel Carrero Pedre
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,43 +1,129 @@
 # Documinty
 
-TODO: Delete this and the text below, and describe your gem
+![Alt text describing image](assets/logo.png)
+
+**Documinty** (alias `dty`) is a lightweight CLI tool to help you document your Ruby codebase as you build features. It lets you:
+
+- Create and manage **features**
+- Tag files with a **node type**, **description**, and **methods**
+- Query documentation by file or by feature
+- Visualize which files belong to a feature (grouped by directory)
+- Search for features by substring
+
+Everything you record lives under a `.documinty/` folder in your project. You can version it alongside your code, making documentation part of your workflow.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/documinty`. To experiment with that code, run `bin/console` for an interactive prompt.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+### Prerequisites
+
+- Ruby ≥ 3.1
+- Bundler (optional, but recommended)
 
-Install the gem and add to the application's Gemfile by executing:
+### From RubyGems
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install documinty
+# or, if you prefer the short alias:
+# gem install dty
+
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+### From Git(development version)
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+git clone git@github.com:yourusername/documinty.git
+cd documinty
+```
+
+Build and install locally
+```
+bundle install
+bundle exec rake build
+gem install pkg/documinty-<VERSION>.gem
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
 
-## Development
+### 1. Go into your existing codebase
+```
+cd path/to/your-app
+```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### 2. Initialize Documinty (creates .documinty/)
+```
+dty init --codebase your-app
+```
+### 3. Create a feature called "user-auth"
+```
+dty feat user-auth
+```
+### 4. Tag a file under "user-auth" as a controller, prompt for description & methods
+```
+dty doc app/controllers/sessions_controller.rb -f user-auth -n controller
+
+#   • You’ll be prompted:
+#     Enter a brief description for this node⚙️:
+#     (e.g.) "Handles login/logout flows"
+#
+#     Enter comma-separated methods for this node🛠️:
+#     (e.g.) :new, :create, :destroy
+```
+### 5. View documentation for that file
+```
+dty show app/controllers/sessions_controller.rb
+```
+### 6. List all defined features
+```
+dty features
+```
+### 7. Show all files under "user-auth"
+```
+dty list_f user-auth
+```
+### 8. Show file structure under "user-auth"
+```
+dty involved_f user-auth
+```
+### 9. Search for features that contain "user"
+```
+dty search_f user
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+### Project layout
+```
+.
+├── exe/
+│   ├── documinty      # primary executable stub
+│   └── dty            # short alias stub
+├── lib/
+│   └── documinty/
+│       ├── cli.rb     # Thor CLI definitions
+│       └── store.rb   # YAML-backed storage logic
+│   └── documinty.rb   # loads version and CLI
+│   └── documinty/version.rb
+├── .documinty/        # created once you run `dty init`
+│   ├── config.yml
+│   └── features/      # per-feature YAML files live here
+├── Rakefile           # builds the gem
+├── documinty.gemspec  # gemspec (metadata + dependencies)
+├── LICENSE.txt
+└── README.md
+```
 
-## Contributing
+### Contributing
+1 - Fork the repository
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/documinty. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/documinty/blob/main/CODE_OF_CONDUCT.md).
+2 - Create a new branch (git checkout -b my-feature)
 
-## License
+3 - Make your changes and add tests if applicable
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+4 - Commit, push, and open a Pull Request
 
-## Code of Conduct
+5 - We’ll review and merge!
 
-Everyone interacting in the Documinty project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/documinty/blob/main/CODE_OF_CONDUCT.md).
+### License
+License
+This project is licensed under the MIT License.
+See LICENSE.txt for details.

data/exe/dty

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "rubygems"
+require "documinty"
+Documinty::CLI.start(ARGV)

data/lib/documinty/cli.rb

@@ -4,6 +4,7 @@ require 'documinty/store'
 
 module Documinty
   class CLI < Thor
+    MAX_DESC_LENGTH = 80
     def self.exit_on_failure?
       true
     end
@@ -15,7 +16,7 @@ module Documinty
     end
 
     desc "feature NAME", "Create a new feature for tagging"
-    def feature(name)
+    def feat(name)
       begin
         store.add_feature(name)
         say "✅ Created feature '#{name}'", :green
@@ -38,14 +39,23 @@ module Documinty
     desc "document FILE", "Tag FILE under an existing feature"
     option :feature, aliases: '-f', required: true, desc: 'Feature name to group under'
     option :node,    aliases: '-n', required: true, desc: 'Node/type label'
-    def document(path)
+    def doc(path)
       begin
+        description = ask("Enter a brief description for this node⚙️:")
+        methods_input = ask("Enter comma-separated methods for this node (or leave blank if none)🛠️:")
+        method_syms = methods_input
+                        .split(",")
+                        .map(&:strip)
+                        .reject(&:empty?)
+                        .map(&:to_sym)
+
         entry = store.add_entry(
-          path:    path,
-          node:    options[:node],
-          feature: options[:feature],
-          timestamp: Time.now.iso8601,
-          description: options[:description] || ask("Enter a brief description for this node:")
+          path:        path,
+          node:        options[:node],
+          feature:     options[:feature],
+          methods:     method_syms,
+          timestamp:   Time.now.iso8601,
+          description: description,
         )
         say "✅ Documented #{entry['path']} as #{entry['node']} under '#{entry['feature']}'", :green
       rescue Error => e
@@ -55,26 +65,81 @@ module Documinty
     end
 
     desc "show FILE", "Display documentation for FILE (node & feature)"
-    def show_documented(path)
+    option :feature, aliases: '-f', desc: 'Only show documentation under this feature'
+    def show(path)
       entries = store.entries_for(path)
+
+      # If a specific feature is requested, filter to those entries
+      if options[:feature]
+        entries = entries.select { |e| Array(e['features'] || e['feature']).include?(options[:feature]) }
+      end
+
       if entries.empty?
-        say "❌ No documentation found for '#{path}'", :red
+        if options[:feature]
+          say "❌ No documentation found for '#{path}' under feature '#{options[:feature]}'", :red
+        else
+          say "❌ No documentation found for '#{path}'", :red
+        end
         exit(1)
       end
 
       entries.each do |e|
-        say "File:        #{e['path']}", :magenta
-        say "Node type:   #{e['node']}", :magenta
-        say "Feature:     #{e['feature']}", :magenta
-        say "Description: #{e['description']}", :magenta unless e['description'].to_s.empty?
-        say "Tagged at:   #{e['timestamp']}", :magenta
-        say "-" * 40, :magenta
+        label_color   = :cyan
+        value_color   = :magenta
+
+        # File
+        say(
+          set_color("File📄", label_color) +
+            ": " +
+            set_color(e['path'], value_color)
+        )
+
+        # Node type
+        say(
+          set_color("Node type⚙️", label_color) +
+            ": " +
+            set_color(e['node'], value_color)
+        )
+
+        # Features
+        say(
+          set_color("Features🏷️", label_color) +
+            ": " +
+            set_color(Array(e['features'] || e['feature']).join(", "), value_color)
+        )
+
+        # Description (only if present)
+        unless e['description'].to_s.empty?
+          say(
+            set_color("Description📝", label_color) +
+              ": " +
+              set_color(truncate(e['description']), value_color)
+          )
+        end
+
+        # Methods (only if present)
+        if e['methods'] && !e['methods'].empty?
+          say(
+            set_color("Methods🛠️", label_color) +
+              ": " +
+              set_color(Array(e['methods']).join(", "), value_color)
+          )
+        end
+
+        # Timestamp
+        say(
+          set_color("Tagged at⏰", label_color) +
+            ": " +
+            set_color(e['timestamp'], value_color)
+        )
+
+        say "-" * 40
       end
     end
 
     desc "untag FILE", "Remove FILE’s tag from an existing feature"
     option :feature, aliases: '-f', required: true, desc: "Feature name"
-    def undocument(path)
+    def untag(path)
       begin
         removed = store.remove_entry(path: path, feature: options[:feature])
         removed.each do |e|
@@ -86,7 +151,7 @@ module Documinty
       end
     end
 
-    desc "show-feature FEATURE", "List all files documented under FEATURE"
+    desc "show_feature FEATURE", "List all files documented under FEATURE"
     def show_feature(feature)
       begin
         entries = store.entries_for_feature(feature)
@@ -99,14 +164,22 @@ module Documinty
         say "No entries under '#{feature}'.", :red
       else
         say "Entries for '#{feature}':"
+        label_color   = :cyan
+        value_color   = :magenta
         entries.each do |e|
-          say "• #{e['path']} (#{e['node']}) – #{e['description']}", :green
+
+
+          # File
+          say(
+            set_color("📄#{e['path']} | ", label_color) +
+              set_color("(#{e['node']}) – #{e['description']}", value_color)
+          )
         end
       end
     end
 
-    desc "show_feature_involved FEATURE", "Display files under FEATURE grouped by directory"
-    def show_feature_involved(feature)
+    desc "involved_f FEATURE", "Display files under FEATURE grouped by directory"
+    def involved_f(feature)
       begin
         entries = store.entries_for_feature(feature)
       rescue Error => e
@@ -131,13 +204,86 @@ module Documinty
 
         entries_in_dir.each do |e|
           # Print each filename line with a file emoji, indented, in green
-          say "    📄 #{File.basename(e['path'])}", :green
+            say "    📄 #{File.basename(e['path'])}", :green
+        end
+      end
+    end
+
+
+    desc "search_f QUERY", "List all features containing QUERY"
+    def search_f(query)
+      matches = store.features.select { |f| f.include?(query) }
+      if matches.empty?
+        say "❌ No features match '#{query}'", :red
+      else
+        say "Matching features:", :cyan
+        matches.each { |f| say "• #{f}", :green }
+      end
+    end
+
+    desc "add_methods FILE", "Prompt for and add methods to an existing documented file"
+    option :feature, aliases: '-f', required: true, desc: "Feature name"
+    def add_methods(path)
+      # Ask interactively for comma-separated methods
+      methods_input = ask("Enter comma-separated methods to add to this node🛠️:")
+      method_syms = methods_input
+                      .split(",")
+                      .map(&:strip)
+                      .reject(&:empty?)
+                      .map(&:to_sym)
+
+      begin
+        entry = store.add_methods(
+          path:        path,
+          feature:     options[:feature],
+          new_methods: method_syms
+        )
+        say "✅ Updated methods for #{entry['path']} under '#{entry['feature']}': #{Array(entry['methods']).join(', ')}", :green
+      rescue Error => e
+        say "❌ #{e.message}", :red
+        exit(1)
+      end
+    end
+
+    desc "describe FILE", "Display only the description for FILE"
+    option :feature, aliases: '-f', desc: "If provided, only show description under that feature"
+    def describe(path)
+      entries = store.entries_for(path)
+
+      # If a specific feature is requested, filter to those entries
+      if options[:feature]
+        entries = entries.select { |e| Array(e['features'] || e['feature']).include?(options[:feature]) }
+      end
+
+      if entries.empty?
+        if options[:feature]
+          say "❌ No description found for '#{path}' under feature '#{options[:feature]}'", :red
+        else
+          say "❌ No description found for '#{path}'", :red
+        end
+        exit(1)
+      end
+
+      entries.each do |e|
+        desc = e['description'].to_s.strip
+        if desc.empty?
+          say "ℹ️  No description provided for '#{path}' under '#{e['feature']}'", :yellow
+        else
+          say "📋 #{path}", :cyan
+          say "--→ #{desc}", :green
         end
       end
     end
 
     private
 
+
+    def truncate(text)
+      return "" unless text
+      return text if text.length <= MAX_DESC_LENGTH
+      text[0, MAX_DESC_LENGTH] + "(…)"
+    end
+
     def store
       @store ||= Store.new(Dir.pwd)
     end

data/lib/documinty/store.rb

@@ -43,7 +43,7 @@ module Documinty
 
     # ─── Entries API ──────────────────────────────────────────────────────────
     # Tag a file under a specific feature
-    def add_entry(path:, node:, feature:, timestamp:, description: '')
+    def add_entry(path:, node:, feature:, methods: [], timestamp:, description: '')
       file = feature_file(feature)
       raise Error, "Feature '#{feature}' does not exist" unless File.exist?(file)
 
@@ -53,6 +53,7 @@ module Documinty
         'path'        => path,
         'node'        => node.to_s,
         'feature'     => feature,
+        'methods'     => Array(methods).map(&:to_s),
         'description' => description.to_s.strip,
         'timestamp'   => timestamp
       }
@@ -102,6 +103,33 @@ module Documinty
       data['entries'] || []
     end
 
+    # Add one or more methods to a documented file under a given feature
+    # @param path [String]       relative file path
+    # @param feature [String]    feature name (must already exist on that entry)
+    # @param new_methods [Array<Symbol>]  list of symbols to add
+    # @return [Hash] the updated entry
+    def add_methods(path:, feature:, new_methods:)
+      file = feature_file(feature)
+      raise Error, "Feature '#{feature}' does not exist" unless File.exist?(file)
+
+      data = YAML.load_file(file) || {}
+      entries = data['entries'] || []
+
+      # Find the exact entry by path + feature
+      entry = entries.find { |e| e['path'] == path && e['feature'] == feature }
+      unless entry
+        raise Error, "No documentation found for '#{path}' under feature '#{feature}'"
+      end
+
+      # Merge existing methods (strings) with new ones, avoid duplicates
+      existing = Array(entry['methods']).map(&:to_s)
+      merged  = (existing + new_methods.map(&:to_s)).uniq
+      entry['methods'] = merged
+
+      File.write(file, data.to_yaml)
+      entry
+    end
+
     private
 
     # Build the path to a feature’s YAML file

data/lib/documinty/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Documinty
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: documinty
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Marcel Carrero Pedre
 bindir: exe
 cert_chain: []
-date: 2025-05-31 00:00:00.000000000 Z
+date: 2025-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -42,6 +42,7 @@ email:
 - marcel.pedre001@outlook.com
 executables:
 - documinty
+- dty
 extensions: []
 extra_rdoc_files: []
 files:
@@ -50,17 +51,18 @@ files:
 - LICENSE.txt
 - README.md
 - exe/documinty
+- exe/dty
 - lib/documinty.rb
 - lib/documinty/cli.rb
 - lib/documinty/store.rb
 - lib/documinty/version.rb
-homepage: https://github.com/yourusername/carreromarcel
+homepage: https://github.com/BatouGlitch/documinty
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/yourusername/carreromarcel
-  source_code_uri: https://github.com/yourusername/carreromarcel
-  changelog_uri: https://github.com/yourusername/carreromarcel/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/BatouGlitch/documinty
+  source_code_uri: https://github.com/BatouGlitch/documinty
+  changelog_uri: https://github.com/BatouGlitch/documinty/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib