slidict 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a58f7f50da42dd170f4f479e90d30f750bfa7e09edc7175b567c34f0637e9d37
-  data.tar.gz: f61880e7f032400e945e5174abae17e15077b0439b352b90af8df2937cf6df9e
+  metadata.gz: a9f6b8851999b92437addc0186d6a047c1c8317145940987514df479e02fabc2
+  data.tar.gz: fb42f714400e77cbc97931d105cef01a8b54776c0ce67db152ce6ce475136caf
 SHA512:
-  metadata.gz: 30f98a358a929f7cd6048f3862183bf8a20c901ea6b6c86a3492865b4abbbdf64de140939c6c754168d4645b66e074788fdbf7a669c1176c7d5e9445b2e4edcd
-  data.tar.gz: d89395639ce333ec905175788aa44da292951560d230529d34f0c1be01b2091a9fc827e4986dff8f02cb07535c0d36562bdc9b05704f13cf6da623f16e532b5c
+  metadata.gz: 88ad47ca34c0e2d7bcf99f118905ba3b7b7f8df571aa4e118080552659564bc2bb7d79d007c3c67a9dc4ebd291e415e6cf423f93299f013485856737e54f7e77
+  data.tar.gz: 781cd459d6c82e62a29bbc8702bea3c7f9d4125d78341e2b13723608ded41e9131af456b87dbfc61525dbc7ebab91da9729fc4465e3b852c0298a96f1e277223

data/.github/workflows/changelog.yml

@@ -5,36 +5,19 @@ on:
     branches:
       - main
 
+permissions:
+  contents: write
+  pull-requests: read
+
 jobs:
   changelog:
     runs-on: ubuntu-latest
 
     steps:
-      - name: Checkout Code
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-
-      - name: Extract version
-        id: version
-        run: |
-          version=$(grep -Eo "[0-9]+\.[0-9]+\.[0-9]+" lib/slidict/version.rb | head -n 1)
-          echo "version=v$version" >> $GITHUB_ENV
-          echo "VERSION_TAG=v$version" >> $GITHUB_ENV
-
-      - name: Check if version file changed
-        id: version_file
-        run: |
-          if git diff --name-only "${{ github.event.before }}" "${{ github.sha }}" | grep -qx "lib/slidict/version.rb"; then
-            echo "changed=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "changed=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Release with release-drafter
+      - name: Update draft release notes
         uses: release-drafter/release-drafter@v5
         with:
           config-name: release-drafter.yml
-          publish: ${{ steps.version_file.outputs.changed == 'true' }}
+          publish: false
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

data/.github/workflows/gem-push.yml

@@ -1,31 +1,51 @@
 name: Ruby Gem
 
 on:
-  push:
-    branches:
-      - main
-    paths:
-      - lib/slidict/version.rb
+  workflow_run:
+    workflows:
+      - Changelog
+    types:
+      - completed
 
 jobs:
   build:
     name: Build + Publish
     runs-on: ubuntu-latest
+    if: github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.head_branch == 'main'
     permissions:
-      contents: read
+      contents: write
       packages: write
 
     steps:
       - uses: actions/checkout@v3
         with:
+          ref: ${{ github.event.workflow_run.head_sha }}
           fetch-depth: 0
 
+      - name: Check if version file changed
+        id: version_file
+        run: |
+          if git diff --name-only HEAD~1 HEAD | grep -qx "lib/slidict/version.rb"; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Extract version
+        if: steps.version_file.outputs.changed == 'true'
+        id: version
+        run: |
+          version=$(grep -Eo "[0-9]+\.[0-9]+\.[0-9]+" lib/slidict/version.rb | head -n 1)
+          echo "tag=v$version" >> "$GITHUB_OUTPUT"
+
       - name: Set up Ruby 3.4
+        if: steps.version_file.outputs.changed == 'true'
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: 3.4.3
 
       - name: Publish to GPR
+        if: steps.version_file.outputs.changed == 'true'
         run: |
           mkdir -p $HOME/.gem
           touch $HOME/.gem/credentials
@@ -38,6 +58,7 @@ jobs:
           OWNER: ${{ github.repository_owner }}
 
       - name: Publish to RubyGems
+        if: steps.version_file.outputs.changed == 'true'
         run: |
           mkdir -p $HOME/.gem
           touch $HOME/.gem/credentials
@@ -47,3 +68,14 @@ jobs:
           gem push *.gem
         env:
           GEM_HOST_API_KEY: "${{ secrets.RUBYGEMS_AUTH_TOKEN }}"
+
+      - name: Publish release notes
+        if: steps.version_file.outputs.changed == 'true'
+        uses: release-drafter/release-drafter@v5
+        with:
+          config-name: release-drafter.yml
+          publish: true
+          tag: ${{ steps.version.outputs.tag }}
+          name: ${{ steps.version.outputs.tag }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

data/AGENTS.md

@@ -21,8 +21,8 @@ OpenAI-compatible chat API.
 
 Run both tests and lint before considering a change complete.
 
-When you add or change a CLI command (or its options), update the "Commands" section
-of `README.md` to document it.
+When you add or change a feature (a CLI command, its options, or any other
+user-facing behavior), update `README.md` to document it.
 
 ## Commit conventions
 

data/README.md

@@ -13,6 +13,7 @@ Unlike traditional slide generators, Slidict focuses on communication before sli
 - Local-first MVP implemented in Ruby
 - Built-in Sinatra server for browsing generated slides from `public/`
 - OpenAI Compatible API support, so you can point Slidict at OpenAI, Ollama, LM Studio, vLLM, or any other server implementing the same `/chat/completions` endpoint
+- Presentation structure linter: checks whether a Markdown/Asciidoc deck's *structure* (not its looks) will land with an audience
 
 ## Requirements
 
@@ -127,6 +128,34 @@ bin/slidict serve -p 4567 -o 0.0.0.0
 `bin/slidict --publish` and `--slide-id` (see [Usage](#usage)) wrap this same `create`/`edit`
 behavior so you can save the slides you just generated straight to slidict.io.
 
+### `slidict lint`
+
+Diagnoses whether a Markdown or Asciidoc slide deck has a structure an audience can
+actually follow -- not whether it looks nice. Diagnosis only; it does not rewrite the
+file. Requires an LLM endpoint (see [Configuration](#configuration)).
+
+```bash
+bin/slidict lint talk.md --llm-base-url http://localhost:11434/v1 --llm-api-key ollama --llm-model llama3
+```
+
+```text
+[warning] Slide 3: this slide's main point is unclear
+[warning] Slide 5: "MCP" is used without first explaining it
+[info] Slide 8: the closing slide is weak; consider adding a one-sentence takeaway for the audience
+```
+
+It checks six things across the whole deck:
+
+1. Is the audience clear?
+2. Can the overall point be stated in one sentence?
+3. Does the deck flow background → problem → solution → result/learning?
+4. Is any single slide overloaded with information?
+5. Is jargon used without first explaining it?
+6. Does the closing slide give the audience a concrete takeaway?
+
+The deck format (`markdown` or `asciidoc`) is auto-detected from the file extension;
+override it with `--format`. Run `bin/slidict lint -h` for the full list of options.
+
 ## Configuration
 
 Slidict generates slides with an LLM through any OpenAI Compatible API. Configure the
@@ -191,6 +220,7 @@ We optimize for communication, not decoration.
 - [x] Interactive CLI
 - [x] Slide generation
 - [x] OpenAI Compatible API support (configurable base URL, so Ollama, LM Studio, and other compatible servers work out of the box)
+- [x] Presentation structure linter (`slidict lint`)
 
 ## License
 

data/lib/slidict/cli/app.rb

@@ -7,7 +7,7 @@ module Slidict
   module Cli
     class App
       def initialize(input: $stdin, output: $stdout, renderer: Output::Renderer.new, auth_client: nil,
-                     credentials: nil, sleeper: Kernel, slides_command: nil, server: nil)
+                     credentials: nil, sleeper: Kernel, slides_command: nil, server: nil, lint_command: nil)
         @input = input
         @output = output
         @renderer = renderer
@@ -16,6 +16,7 @@ module Slidict
         @sleeper = sleeper
         @slides_command = slides_command
         @server = server
+        @lint_command = lint_command
       end
 
       def run(argv = [])
@@ -24,6 +25,7 @@ module Slidict
         return auth if options[:command] == "auth"
         return slides(options[:args]) if options[:command] == "slides"
         return serve(options[:args]) if options[:command] == "serve"
+        return lint(options[:args]) if options[:command] == "lint"
 
         config = build_config(options)
         client = llm_client_for(config)
@@ -94,6 +96,13 @@ module Slidict
           return options
         end
 
+        if args.first == "lint"
+          args.shift
+          options[:command] = "lint"
+          options[:args] = args
+          return options
+        end
+
         until args.empty?
           case (arg = args.shift)
           when "-h", "--help"
@@ -198,6 +207,10 @@ module Slidict
         server.run(args)
       end
 
+      def lint(args)
+        lint_command.run(args)
+      end
+
       def publish_to_slidict(deck, content, options)
         slides_command.publish(
           id: options[:slide_id],
@@ -216,6 +229,10 @@ module Slidict
         @server ||= Serve.new(output: @output)
       end
 
+      def lint_command
+        @lint_command ||= Lint.new(output: @output)
+      end
+
       def body_format_for(framework)
         Output::Format.fetch(framework).body_format
       end
@@ -246,6 +263,7 @@ module Slidict
           Usage: slidict auth
           Usage: slidict slides <list|show|create|edit> [options]
           Usage: slidict serve [sinatra options]
+          Usage: slidict lint <file> [options]
 
           Generate presentation source files from a short conversation.
 
@@ -253,6 +271,8 @@ module Slidict
             auth             Authenticate the CLI with GitHub and save a CLI access token
             slides           Manage your slides on slidict.io (run `slidict slides -h` for details)
             serve            Serve slide files from ./public with Sinatra
+            lint             Check whether a slide deck's structure will land with its audience
+                             (run `slidict lint -h` for details)
 
           Options:
               --topic TEXT       Presentation topic

data/lib/slidict/cli/lint.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Slidict
+  module Cli
+    # Implements `slidict lint <file>`: diagnoses whether a Markdown/Asciidoc
+    # slide deck has a structure that an audience can actually follow (not
+    # whether it looks nice). Diagnosis only -- it does not rewrite the file.
+    class Lint
+      ASCIIDOC_EXTENSIONS = %w[.adoc .asciidoc].freeze
+
+      def initialize(output:, linter_factory: nil, renderer: Slidict::Lint::Renderer.new)
+        @output = output
+        @linter_factory = linter_factory || method(:default_linter)
+        @renderer = renderer
+      end
+
+      def run(argv)
+        options = parse(argv)
+        return print_help if options[:help] || options[:path].nil?
+        return file_not_found(options[:path]) unless File.exist?(options[:path])
+
+        run_lint(options)
+      rescue ArgumentError => e
+        print_usage_error(e)
+      rescue Slidict::Lint::Linter::Error, Llm::Client::Error => e
+        print_error(e)
+      end
+
+      private
+
+      def run_lint(options)
+        config = build_config(options)
+        return llm_required unless config.llm_enabled?
+
+        print_findings(lint(options, config))
+      end
+
+      def lint(options, config)
+        @linter_factory.call(config).lint(File.read(options[:path]), format: format_for(options))
+      end
+
+      def print_usage_error(error)
+        print_error(error)
+        @output.puts
+        print_help
+        1
+      end
+
+      def print_error(error)
+        @output.puts "Error: #{error.message}"
+        1
+      end
+
+      def parse(argv)
+        args = argv.dup
+        options = { path: extract_path!(args) }
+        parse_options!(args, options)
+        options
+      end
+
+      def extract_path!(args)
+        args.shift unless args.first.to_s.start_with?("-")
+      end
+
+      def parse_options!(args, options)
+        until args.empty?
+          case (arg = args.shift)
+          when "-h", "--help" then options[:help] = true
+          when "--format" then options[:format] = fetch_value!(args, arg)
+          when "--llm-base-url" then options[:llm_base_url] = fetch_value!(args, arg)
+          when "--llm-api-key" then options[:llm_api_key] = fetch_value!(args, arg)
+          when "--llm-model" then options[:llm_model] = fetch_value!(args, arg)
+          else raise ArgumentError, "unknown option #{arg}"
+          end
+        end
+      end
+
+      def fetch_value!(args, option)
+        value = args.shift
+        raise ArgumentError, "#{option} requires a value" if value.nil? || value.start_with?("-")
+
+        value
+      end
+
+      def build_config(options)
+        Config.from_env.merge(
+          base_url: options[:llm_base_url],
+          api_key: options[:llm_api_key],
+          model: options[:llm_model]
+        )
+      end
+
+      def default_linter(config)
+        client = Llm::Client.new(base_url: config.base_url, api_key: config.api_key, model: config.model)
+        Slidict::Lint::Linter.new(client: client)
+      end
+
+      def format_for(options)
+        return options[:format] if options[:format]
+
+        ASCIIDOC_EXTENSIONS.include?(File.extname(options[:path]).downcase) ? "asciidoc" : "markdown"
+      end
+
+      def print_findings(findings)
+        @output.puts(findings.empty? ? "No issues found." : @renderer.render(findings))
+        0
+      end
+
+      def file_not_found(path)
+        @output.puts "Error: file not found: #{path}"
+        1
+      end
+
+      def llm_required
+        @output.puts "Error: lint requires an LLM endpoint (--llm-base-url or SLIDICT_LLM_BASE_URL)"
+        1
+      end
+
+      def print_help
+        @output.puts <<~HELP
+          Usage: slidict lint <file> [options]
+          Diagnoses whether a slide deck's structure will land with its audience.
+              --format FORMAT     markdown or asciidoc (default: auto-detected from extension)
+              --llm-base-url URL  OpenAI Compatible API base URL (env: SLIDICT_LLM_BASE_URL)
+              --llm-api-key KEY   API key for the LLM endpoint (env: SLIDICT_LLM_API_KEY)
+              --llm-model NAME    Model name to request (env: SLIDICT_LLM_MODEL, default: gpt-4o-mini)
+          -h, --help               Show this help
+        HELP
+        0
+      end
+    end
+  end
+end

data/lib/slidict/lint/finding.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Slidict
+  module Lint
+    # A single diagnostic produced by the linter: which slide it concerns,
+    # how severe it is ("warning" blocks understanding, "info" is a
+    # suggestion), and the human-readable message to show the user.
+    Finding = Struct.new(:slide, :severity, :message, keyword_init: true)
+  end
+end

data/lib/slidict/lint/linter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Slidict
+  module Lint
+    # Orchestrates a lint run: splits the raw deck source into slides and
+    # asks the LLM client to diagnose the presentation's structure.
+    class Linter
+      class Error < StandardError; end
+
+      def initialize(client:)
+        @client = client
+      end
+
+      def lint(content, format: "markdown")
+        slides = SlideParser.parse(content, format: format)
+        raise Error, "no slides found in the given file" if slides.empty?
+
+        @client.lint_slides(slides)
+      end
+    end
+  end
+end

data/lib/slidict/lint/renderer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Slidict
+  module Lint
+    # Formats findings as one line per finding:
+    #   [warning] Slide 3: this slide's main point is unclear
+    class Renderer
+      def render(findings)
+        findings.sort_by(&:slide).map { |finding| line_for(finding) }.join("\n")
+      end
+
+      private
+
+      def line_for(finding)
+        "[#{finding.severity}] Slide #{finding.slide}: #{finding.message}"
+      end
+    end
+  end
+end

data/lib/slidict/lint/slide_parser.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Slidict
+  module Lint
+    # Splits raw Markdown/Asciidoc slide source into one text block per
+    # slide, so the linter can refer to slides by number. Frontmatter
+    # (Markdown) and the document title/preamble (Asciidoc) are dropped
+    # since they are not slides a reader sees.
+    class SlideParser
+      MARKDOWN_SEPARATOR = /\A-{3,}\s*\z/
+      ASCIIDOC_SLIDE_HEADING = /\A==\s+/
+      MARKDOWN_HEADING = /\A#\s+/
+
+      def self.parse(content, format: "markdown")
+        format == "asciidoc" ? parse_asciidoc(content) : parse_markdown(content)
+      end
+
+      def self.parse_markdown(content)
+        blocks = split_lines(content, MARKDOWN_SEPARATOR)
+        blocks = blocks.drop(2) if content.lines.first&.match?(MARKDOWN_SEPARATOR)
+
+        if blocks.size <= 1
+          by_heading = split_lines(content, MARKDOWN_HEADING, keep_separator: true, drop_preamble: true)
+          blocks = by_heading unless by_heading.empty?
+        end
+
+        clean(blocks)
+      end
+      private_class_method :parse_markdown
+
+      def self.parse_asciidoc(content)
+        clean(split_lines(content, ASCIIDOC_SLIDE_HEADING, keep_separator: true, drop_preamble: true))
+      end
+      private_class_method :parse_asciidoc
+
+      # Splits `content` into blocks every time a line matches `separator`.
+      # With keep_separator: true the matching line starts a new block
+      # instead of being discarded (used for heading-based splitting).
+      # With drop_preamble: true, any lines before the first match are
+      # discarded rather than kept as a leading block.
+      def self.split_lines(content, separator, keep_separator: false, drop_preamble: false)
+        blocks = []
+        current = drop_preamble ? nil : []
+        content.each_line do |line|
+          current = append_line(blocks, current, line, separator, keep_separator)
+        end
+        blocks << current.join if current
+        blocks
+      end
+      private_class_method :split_lines
+
+      def self.append_line(blocks, current, line, separator, keep_separator)
+        return current << line if current && !line.match?(separator)
+
+        blocks << current.join if current
+        return current unless line.match?(separator)
+
+        keep_separator ? [line] : []
+      end
+      private_class_method :append_line
+
+      def self.clean(blocks)
+        blocks.map(&:strip).reject(&:empty?)
+      end
+      private_class_method :clean
+    end
+  end
+end

data/lib/slidict/llm/client.rb

@@ -34,6 +34,14 @@ module Slidict
         slides_from(content)
       end
 
+      # slide_texts is an array of slide bodies (1-indexed by position) as
+      # produced by Slidict::Lint::SlideParser. Returns an array of
+      # Slidict::Lint::Finding.
+      def lint_slides(slide_texts)
+        content = chat_completion(lint_prompt_for(slide_texts))
+        findings_from(content)
+      end
+
       private
 
       def prompt_for(deck)
@@ -51,6 +59,66 @@ module Slidict
         PROMPT
       end
 
+      LINT_PROMPT_TEMPLATE = <<~PROMPT
+        You are a presentation structure linter for tech talks and lightning talks.
+        Your goal is not to judge how the slides look, but to diagnose whether the
+        structure will actually land with an audience.
+
+        Evaluate the deck as a whole against these six checks:
+
+        1. Is the audience clear (who is this talk for)?
+        2. Can the overall point be stated in one sentence?
+        3. Does the deck flow background -> problem -> solution -> result/learning
+           (call out where the flow breaks down)?
+        4. Is any single slide overloaded with information?
+        5. Is jargon used without first explaining it?
+        6. Does the closing slide give the audience one concrete takeaway?
+
+        For each finding, name the single slide it relates to most. For deck-wide
+        findings (unclear audience, unclear thesis, etc.), point to the slide where
+        the problem is most visible, or slide 1 if you cannot tell.
+
+        Decide severity using these rules:
+        - warning: likely to block audience understanding (checks 1-5)
+        - info: a suggestion that would make things better (check 6, or minor polish)
+
+        Here is the slide content ("--- Slide N ---" marks each slide boundary):
+
+        %<numbered>s
+
+        Respond with a JSON array of findings only. Each item must be an object of
+        the form {"slide": <integer>, "severity": "warning" or "info", "message": "<one sentence>"}.
+
+        Do not include any commentary, markdown code fences, or text other than the
+        JSON array. Return an empty array [] if you find no issues.
+      PROMPT
+
+      def lint_prompt_for(slide_texts)
+        numbered = slide_texts.each_with_index.map { |text, i| "--- Slide #{i + 1} ---\n#{text}" }.join("\n\n")
+        format(LINT_PROMPT_TEMPLATE, numbered: numbered)
+      end
+
+      def findings_from(content)
+        parsed = JSON.parse(extract_json_array(content))
+        raise Error, "expected a JSON array of findings" unless parsed.is_a?(Array)
+
+        parsed.map { |item| finding_from(item) }
+      rescue JSON::ParserError, KeyError, ArgumentError, TypeError => e
+        raise Error, "could not parse model response: #{e.message}"
+      end
+
+      def finding_from(item)
+        Lint::Finding.new(
+          slide: Integer(item.fetch("slide")),
+          severity: normalize_severity(item["severity"]),
+          message: item.fetch("message")
+        )
+      end
+
+      def normalize_severity(value)
+        %w[warning info].include?(value) ? value : "info"
+      end
+
       def chat_completion(prompt)
         response = JSON.parse(post_chat_completion(prompt))
         content = response.dig("choices", 0, "message", "content")

data/lib/slidict/version.rb

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

data/lib/slidict.rb

@@ -3,6 +3,7 @@
 require "time"
 
 require_relative "slidict/cli/app"
+require_relative "slidict/cli/lint"
 require_relative "slidict/cli/serve"
 require_relative "slidict/cli/slides"
 require_relative "slidict/config"
@@ -10,6 +11,10 @@ require_relative "slidict/deck"
 require_relative "slidict/external/slidict_io/auth"
 require_relative "slidict/external/slidict_io/client"
 require_relative "slidict/external/slidict_io/credentials"
+require_relative "slidict/lint/finding"
+require_relative "slidict/lint/linter"
+require_relative "slidict/lint/renderer"
+require_relative "slidict/lint/slide_parser"
 require_relative "slidict/llm/client"
 require_relative "slidict/output/format"
 require_relative "slidict/output/renderer"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slidict
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Yusuke Abe
@@ -74,6 +74,7 @@ files:
 - Rakefile
 - lib/slidict.rb
 - lib/slidict/cli/app.rb
+- lib/slidict/cli/lint.rb
 - lib/slidict/cli/serve.rb
 - lib/slidict/cli/slides.rb
 - lib/slidict/config.rb
@@ -81,6 +82,10 @@ files:
 - lib/slidict/external/slidict_io/auth.rb
 - lib/slidict/external/slidict_io/client.rb
 - lib/slidict/external/slidict_io/credentials.rb
+- lib/slidict/lint/finding.rb
+- lib/slidict/lint/linter.rb
+- lib/slidict/lint/renderer.rb
+- lib/slidict/lint/slide_parser.rb
 - lib/slidict/llm/client.rb
 - lib/slidict/output/format.rb
 - lib/slidict/output/renderer.rb