docsterra 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 778f499c80a748af7e5848eb9a68287b1e299a47afa54a0ff20e9de9182053a3
+  data.tar.gz: 8a284d3e4dcbba8921270f6211a3f5b7dde5eb5519d64e7f91f893031d2967eb
+SHA512:
+  metadata.gz: 4dbcbab92c1caa74ddb7f3c321c21da185ed1598211e5d02b6bee9291dfb1a0bca9937531e59744ca4d7cc53d1f6dce034ec48a97b73915ec8521a589b9feb39
+  data.tar.gz: aa5fc647fd2545013654b6c08955c94cc70222061bba44b6025cccf814248e7de65cc1eaa20ad4d999a34b1c51aaf7932d6133daa7c5606eb3535ba616327ebe

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 (2026-02-26)
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,133 @@
+# Docsterra
+
+`docsterra` is a Ruby gem / CLI that parses Terraform (`.tf`) files and generates infrastructure design documentation in Markdown.
+
+Current implementation focuses on GCP Terraform resources and produces:
+
+- resource inventory tables
+- Mermaid network diagrams
+- cross-product dependency diagrams
+- security summaries (IAM / firewall / warnings)
+- cost-related spec summaries (non-billing estimate metadata)
+
+## Installation
+
+```bash
+gem install docsterra
+```
+
+Or from a Gemfile:
+
+```ruby
+gem "docsterra"
+```
+
+## Quick Start
+
+Single Terraform root:
+
+```bash
+docsterra generate ./terraform
+```
+
+Multiple products (cross-product dependency analysis enabled):
+
+```bash
+docsterra generate ./product-a/terraform ./product-b/terraform ./shared/terraform -o ./docs/infrastructure.md
+```
+
+Dry-run summary:
+
+```bash
+docsterra check ./terraform
+```
+
+## CLI Reference
+
+### Commands
+
+```bash
+docsterra generate [PATHS...]
+docsterra check [PATHS...]
+docsterra version
+```
+
+### Options
+
+- `-o`, `--output`: output markdown path (default: `./infrastructure.md`)
+- `-c`, `--config`: config file path (default: `.docsterra.yml`)
+- `-s`, `--sections`: comma-separated sections (`all`, `resources`, `network`, `security`, `cost`)
+- `-f`, `--format`: output format (currently only `markdown`)
+- `-v`, `--verbose`: verbose output
+- `--ignore`: ignore glob patterns (repeatable via Thor array syntax)
+
+## Library Usage
+
+```ruby
+require "docsterra"
+
+doc = Docsterra.generate("./terraform")
+doc.save("./docs/infrastructure.md")
+puts doc.to_markdown
+
+summary = Docsterra.check("./terraform")
+puts summary[:resource_count]
+```
+
+## Configuration (`.docsterra.yml`)
+
+```yaml
+products:
+  - name: "Web Application"
+    path: "./product-web/terraform"
+  - name: "Shared Infrastructure"
+    path: "./shared/terraform"
+    shared: true
+
+output:
+  path: "./docs/infrastructure.md"
+  sections:
+    - resources
+    - network
+    - security
+    - cost
+
+resource_attributes:
+  google_compute_instance:
+    - machine_type
+    - zone
+    - labels.env
+
+ignore:
+  - "**/examples/**"
+```
+
+## Output Example (Sections)
+
+- `## Overview`
+- `## Cross-Product Dependencies` (Mermaid)
+- `## {Product}`
+- `### Resources`
+- `### Network Configuration` (Mermaid)
+- `### Security Settings`
+- `### Cost Estimation`
+- `## Appendix`
+
+## Limitations
+
+- HCL parsing is best-effort. Unsupported expressions are preserved as `RawExpr` and rendered as text.
+- Remote modules are not parsed (metadata only).
+- Local modules are parsed recursively, but complex module evaluation/output resolution is not performed.
+- No real-time GCP pricing lookup; cost output is resource spec metadata only.
+- Terraform state / `terraform plan` JSON is not consumed.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/docsterra

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "terradoc"
+
+Terradoc::CLI.start(ARGV)

data/lib/docsterra/analyzer/cost_analyzer.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Docsterra
+  module Analyzer
+    class CostAnalyzer
+      CostItem = Struct.new(:resource_name, :resource_type, :spec, :region, :note, :resource, keyword_init: true)
+
+      def analyze(resources)
+        resources.filter_map do |resource|
+          build_cost_item(resource)
+        end
+      end
+
+      private
+
+      def build_cost_item(resource)
+        case resource.type
+        when "google_compute_instance"
+          CostItem.new(
+            resource_name: resource.attribute_text("name") || resource.name,
+            resource_type: resource.type,
+            spec: resource.attribute_text("machine_type"),
+            region: resource.attribute_text("zone"),
+            note: nil,
+            resource: resource
+          )
+        when "google_container_cluster"
+          node_type = resource.attribute_text("node_config.machine_type")
+          node_count = resource.attribute_text("initial_node_count")
+          CostItem.new(
+            resource_name: resource.attribute_text("name") || resource.name,
+            resource_type: resource.type,
+            spec: [node_type, node_count && "x #{node_count}"].compact.join(" "),
+            region: resource.attribute_text("location"),
+            note: "Autopilot: #{truthy_string(resource.attribute_ruby('enable_autopilot'))}",
+            resource: resource
+          )
+        when "google_container_node_pool"
+          CostItem.new(
+            resource_name: resource.attribute_text("name") || resource.name,
+            resource_type: resource.type,
+            spec: resource.attribute_text("node_config.machine_type"),
+            region: resource.attribute_text("location") || resource.attribute_text("region"),
+            note: node_pool_note(resource),
+            resource: resource
+          )
+        when "google_sql_database_instance"
+          CostItem.new(
+            resource_name: resource.attribute_text("name") || resource.name,
+            resource_type: resource.type,
+            spec: resource.attribute_text("settings.tier") || resource.attribute_text("tier"),
+            region: resource.attribute_text("region"),
+            note: "HA: #{truthy_string((resource.attribute_text('settings.availability_type') || resource.attribute_text('availability_type')).to_s == 'REGIONAL')}",
+            resource: resource
+          )
+        when "google_storage_bucket"
+          CostItem.new(
+            resource_name: resource.attribute_text("name") || resource.name,
+            resource_type: resource.type,
+            spec: nil,
+            region: resource.attribute_text("location"),
+            note: "class: #{resource.attribute_text('storage_class')}",
+            resource: resource
+          )
+        when "google_redis_instance"
+          CostItem.new(
+            resource_name: resource.attribute_text("name") || resource.name,
+            resource_type: resource.type,
+            spec: "memory_size_gb=#{resource.attribute_text('memory_size_gb')}",
+            region: resource.attribute_text("region"),
+            note: "tier: #{resource.attribute_text('tier')}",
+            resource: resource
+          )
+        when "google_compute_disk"
+          CostItem.new(
+            resource_name: resource.attribute_text("name") || resource.name,
+            resource_type: resource.type,
+            spec: "#{resource.attribute_text('size')}GB #{resource.attribute_text('type')}".strip,
+            region: resource.attribute_text("zone"),
+            note: nil,
+            resource: resource
+          )
+        end
+      end
+
+      def truthy_string(value)
+        case value
+        when true then "yes"
+        when false then "no"
+        else
+          value.nil? ? "unknown" : value.to_s
+        end
+      end
+
+      def node_pool_note(resource)
+        min = resource.attribute_text("autoscaling.min_node_count")
+        max = resource.attribute_text("autoscaling.max_node_count")
+        return nil if min.nil? && max.nil?
+
+        "autoscaling: #{min || '?'}-#{max || '?'}"
+      end
+    end
+  end
+end

data/lib/docsterra/analyzer/dependency_analyzer.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module Docsterra
+  module Analyzer
+    class DependencyAnalyzer
+      def analyze(projects)
+        relationships = []
+        resource_index = build_resource_index(projects)
+        name_index = build_name_index(projects)
+        string_name_index = build_string_name_index(projects)
+        service_account_index = build_service_account_index(projects)
+
+        projects.each do |project|
+          relationships.concat(detect_reference_relationships(project, resource_index))
+          relationships.concat(detect_data_source_relationships(project, name_index))
+          relationships.concat(detect_shared_name_relationships(project, string_name_index))
+          relationships.concat(detect_service_account_relationships(project, service_account_index))
+        end
+
+        deduplicate(relationships)
+      end
+
+      private
+
+      def build_resource_index(projects)
+        projects.each_with_object({}) do |project, index|
+          project.resources.each { |resource| index[resource.identifier] = resource }
+        end
+      end
+
+      def build_name_index(projects)
+        projects.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |project, index|
+          project.resources.each do |resource|
+            key = [resource.type, resource.attribute_text("name") || resource.attribute_text("dataset_id") || resource.name]
+            index[key] << resource
+          end
+        end
+      end
+
+      def build_service_account_index(projects)
+        projects.each_with_object({}) do |project, index|
+          project.resources.select { |resource| resource.type == "google_service_account" }.each do |sa|
+            account_id = sa.attribute_text("account_id")
+            email = sa.attribute_text("email")
+            [account_id, email].compact.each { |key| index[key] = sa }
+          end
+        end
+      end
+
+      def build_string_name_index(projects)
+        projects.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |project, index|
+          project.resources.each do |resource|
+            next unless shareable_name_target?(resource)
+
+            names_for_resource(resource).each do |name|
+              next if name.nil? || name.empty?
+
+              index[name] << resource
+            end
+          end
+        end
+      end
+
+      def detect_reference_relationships(project, resource_index)
+        project.resources.flat_map do |resource|
+          resource.references.filter_map do |ref|
+            target = resource_index[reference_identifier(ref)]
+            next unless target
+            next if target.project == project
+
+            rel_type = target.project.shared? ? :shared_resource : relation_type_for_target(target)
+            Model::Relationship.new(
+              source: resource,
+              target: target,
+              type: rel_type,
+              detail: "Reference #{ref}"
+            )
+          end
+        end
+      end
+
+      def detect_data_source_relationships(project, name_index)
+        project.data_sources.filter_map do |data_source|
+          lookup_key = [data_source.type, data_source.attribute_text("name") || data_source.attribute_text("dataset_id")]
+          matches = name_index[lookup_key].reject { |resource| resource.project == project }
+          next if matches.empty?
+
+          target = matches.first
+          rel_type = target.project.shared? ? :shared_resource : relation_type_for_target(target)
+          Model::Relationship.new(
+            source: project,
+            target: target.project,
+            type: rel_type,
+            detail: "Data source #{data_source.type}.#{data_source.name} uses #{lookup_key[1]}"
+          )
+        end.compact
+      end
+
+      def detect_service_account_relationships(project, service_account_index)
+        project.resources.filter { |resource| resource.type.match?(/_iam_(member|binding)\z/) }.filter_map do |resource|
+          members = Array(resource.attribute_ruby("members")) + [resource.attribute_text("member")]
+          target_sa = members.compact.lazy.map { |member| find_service_account_in_member(member.to_s, service_account_index) }.find(&:itself)
+          next unless target_sa
+          next if target_sa.project == project
+
+          Model::Relationship.new(
+            source: resource,
+            target: target_sa,
+            type: :iam,
+            detail: "IAM member uses service account from #{target_sa.project.name}"
+          )
+        end
+      end
+
+      def detect_shared_name_relationships(project, string_name_index)
+        project.resources.flat_map do |resource|
+          flattened_attribute_strings(resource.attributes).filter_map do |text|
+            next unless candidate_shared_name?(text)
+
+            target = string_name_index[text].find { |candidate| candidate.project != project }
+            next unless target
+
+            rel_type = target.project.shared? ? :shared_resource : relation_type_for_target(target)
+            Model::Relationship.new(
+              source: resource,
+              target: target,
+              type: rel_type,
+              detail: "String reference uses shared resource name #{text}"
+            )
+          end
+        end
+      end
+
+      def find_service_account_in_member(member, service_account_index)
+        service_account_index.each do |key, resource|
+          return resource if key && member.include?(key)
+        end
+        nil
+      end
+
+      def reference_identifier(ref)
+        return nil unless ref
+
+        parts = ref.split(".")
+        return nil if parts.length < 2
+
+        parts[0, 2].join(".")
+      end
+
+      def relation_type_for_target(target)
+        target.category == :networking ? :network : :reference
+      end
+
+      def names_for_resource(resource)
+        [
+          resource.attribute_text("name"),
+          resource.attribute_text("dataset_id"),
+          resource.attribute_text("account_id"),
+          resource.name
+        ].compact.uniq
+      end
+
+      def shareable_name_target?(resource)
+        %i[networking iam messaging].include?(resource.category) || resource.type == "google_pubsub_topic"
+      end
+
+      def flattened_attribute_strings(value)
+        case value
+        when Hash
+          value.values.flat_map { |child| flattened_attribute_strings(child) }
+        when Array
+          value.flat_map { |child| flattened_attribute_strings(child) }
+        else
+          [Parser::ExpressionInspector.to_ruby(value)]
+        end.map(&:to_s).reject(&:empty?)
+      end
+
+      def candidate_shared_name?(text)
+        return false if text.start_with?("http://", "https://")
+        return false if text.match?(/\A\d+\z/)
+
+        text.length >= 3
+      end
+
+      def deduplicate(relationships)
+        relationships.each_with_object([]) do |relationship, unique|
+          unique << relationship unless unique.any? { |existing| existing.key == relationship.key }
+        end
+      end
+    end
+  end
+end

data/lib/docsterra/analyzer/network_analyzer.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Docsterra
+  module Analyzer
+    class NetworkAnalyzer
+      NETWORK_TYPES = %w[
+        google_compute_network
+        google_compute_subnetwork
+        google_compute_firewall
+        google_compute_global_address
+        google_compute_address
+        google_compute_forwarding_rule
+        google_compute_global_forwarding_rule
+        google_compute_router
+        google_compute_router_nat
+        google_dns_managed_zone
+        google_dns_record_set
+      ].freeze
+
+      LOAD_BALANCER_TYPES = %w[
+        google_compute_forwarding_rule
+        google_compute_global_forwarding_rule
+      ].freeze
+
+      def analyze(resources)
+        vpcs = resources.select { |resource| resource.type == "google_compute_network" }
+        subnets = resources.select { |resource| resource.type == "google_compute_subnetwork" }
+        firewalls = resources.select { |resource| resource.type == "google_compute_firewall" }
+        load_balancers = resources.select { |resource| LOAD_BALANCER_TYPES.include?(resource.type) }
+        endpoints = resources.reject { |resource| NETWORK_TYPES.include?(resource.type) }
+        links = build_links(resources, vpcs)
+
+        Model::Network.new(
+          vpcs: vpcs,
+          subnets: subnets,
+          firewall_rules: firewalls,
+          load_balancers: load_balancers,
+          endpoints: endpoints,
+          links: links
+        )
+      end
+
+      private
+
+      def build_links(resources, vpcs)
+        vpc_lookup = vpcs.each_with_object({}) do |vpc, index|
+          index[vpc.identifier] = vpc
+        end
+
+        resources.flat_map do |resource|
+          refs = Array(resource.references)
+          refs.filter_map do |ref|
+            target = target_from_reference(ref, vpc_lookup)
+            next unless target
+
+            {
+              source: resource,
+              target: target,
+              type: :network,
+              detail: "references #{ref}"
+            }
+          end
+        end.uniq
+      end
+
+      def target_from_reference(ref, vpc_lookup)
+        return nil unless ref
+
+        # ex: google_compute_network.shared.id -> google_compute_network.shared
+        parts = ref.split(".")
+        return nil if parts.length < 2
+
+        identifier = parts[0, 2].join(".")
+        vpc_lookup[identifier]
+      end
+    end
+  end
+end

data/lib/docsterra/analyzer/resource_analyzer.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Docsterra
+  module Analyzer
+    class ResourceAnalyzer
+      def initialize(registry: Parser::ResourceRegistry.new)
+        @registry = registry
+      end
+
+      def analyze(project)
+        project.resources = build_resources(project.resource_blocks, project, kind: :resource)
+        project.data_sources = build_resources(project.data_blocks, project, kind: :data)
+        project.resources
+      end
+
+      private
+
+      def build_resources(entries, project, kind:)
+        entries.map do |entry|
+          block = entry.block
+          resource_type = block.labels[0]
+          name = block.labels[1] || block.labels[0]
+          attributes = build_attribute_tree(block.body)
+          refs = collect_references_from_attributes(attributes)
+          meta = extract_meta(attributes)
+
+          Model::Resource.new(
+            type: resource_type,
+            name: name,
+            attributes: attributes,
+            project: project,
+            references: refs + Array(meta[:depends_on]),
+            meta: meta,
+            source_file: entry.file,
+            comment: block.comment,
+            kind: kind,
+            display_name: @registry.display_name_for(resource_type),
+            category: @registry.category_for(resource_type),
+            key_attributes: @registry.key_attributes_for(resource_type)
+          )
+        end
+      end
+
+      def build_attribute_tree(items)
+        tree = {}
+
+        Array(items).each do |item|
+          case item
+          when Parser::AST::Attribute
+            tree[item.key] = item.value
+          when Parser::AST::Block
+            block_hash = build_attribute_tree(item.body)
+            block_hash["__labels"] = item.labels unless item.labels.nil? || item.labels.empty?
+            tree[item.type] ||= []
+            tree[item.type] << block_hash
+          end
+        end
+
+        tree
+      end
+
+      def collect_references_from_attributes(value)
+        case value
+        when Hash
+          value.values.flat_map { |child| collect_references_from_attributes(child) }.uniq
+        when Array
+          value.flat_map { |child| collect_references_from_attributes(child) }.uniq
+        else
+          Parser::ExpressionInspector.collect_references(value)
+        end
+      end
+
+      def extract_meta(attributes)
+        {
+          count: attributes["count"],
+          for_each: attributes["for_each"],
+          depends_on: normalize_depends_on(attributes["depends_on"])
+        }.compact
+      end
+
+      def normalize_depends_on(node)
+        return [] if node.nil?
+
+        case node
+        when Parser::AST::ListExpr
+          node.elements.map { |element| Parser::ExpressionInspector.to_text(element) }.compact
+        when Parser::AST::RawExpr
+          [node.text]
+        else
+          [Parser::ExpressionInspector.to_text(node)]
+        end
+      end
+    end
+  end
+end