snitcher_reports 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 77c2bf289fd3ba179a8887bc78c48382583f2fde533f4fdd26d37da7b696aaa8
+  data.tar.gz: aa5969150911043f511b11b95e76caced6086498052873d7055accd2cf341116
+SHA512:
+  metadata.gz: 287d3f7a2d68646a6ddcb507df366cb85c7ccf2bb6f0e43403380b36327d46d78d9ae6de9262c90d3fa38cacce045ed09a6867674abbafe68ff6a03c5fb2cc66
+  data.tar.gz: 2c9c951e9fbe7e8f5dd23909608026cc034a5d4a5c5d48ae8b926fb477f396181831fa779e5dd3b81bcaee315ba3d7262002a314da1a37b0c3afcfed428af625

data/.snitcher.yml.example

@@ -0,0 +1,135 @@
+# Snitcher project configuration
+#
+# Status names are language-specific (e.g. Polish, German), so the values below are
+# only a starting point — replace them with the names your workspace actually uses.
+#
+# Copy this file to .snitcher.yml and adjust the values to match your workspace.
+
+version: 1
+sources:
+  clickup:
+    # Optional: limit reports to specific ClickUp spaces.
+    # Omit or leave empty to include all spaces. Names are case-sensitive.
+    # This also limits where archived lists are looked for.
+    # spaces:
+    #   - Engineering
+    #   - QA
+    # NOTE: done_statuses and in_progress_statuses are NOT used to filter tasks fetched
+    # from ClickUp. The request narrows by date_done_gt/lt, the only completion-date
+    # parameter the API accepts, and the report then keeps the tasks whose date_closed
+    # falls inside the period. Dates are more reliable than status names — lists and
+    # folders can override workspace-level statuses via the override_statuses flag, so
+    # status names are not consistent across a workspace.
+    # These values are kept for potential future use (e.g. list/folder-scoped reports).
+    done_statuses:
+      - "complete"
+      - "closed"
+    in_progress_statuses:
+      - "in progress"
+    todo_statuses:
+      - "to do"
+      - "open"
+  jira:
+    # Optional: limit reports to specific JIRA projects.
+    # Omit or leave empty to include all projects.
+    # projects:
+    #   - SCRUM
+    #   - XSP
+    # NOTE: leave the status lists out unless your classification differs from Jira's
+    # own. Snitcher reads each status's category from the instance itself
+    # (/rest/api/3/status), which is language-independent and covers statuses added
+    # later, and the names below take precedence over it — filling them in with Jira's
+    # own defaults replaces a correct answer with a frozen copy of it. Set them to
+    # override Jira, e.g. to count "In Review" as active work when Jira files it as
+    # not-started:
+    # in_progress_statuses:
+    #   - "In Review"
+  linear:
+    done_statuses:
+      - "Done"
+      - "Cancelled"
+    in_progress_statuses:
+      - "In Progress"
+      - "In Review"
+    todo_statuses:
+      - "Todo"
+      - "Backlog"
+  git:
+    # Optional: path to the git repository (default: current directory).
+    # repo_path: /path/to/your/project
+    #
+    # Git identity resolution (both `user` and `emails` accept a single string OR a
+    # list of strings, since one person may commit under several addresses — work
+    # laptop, personal, GitHub noreply):
+    #
+    # A requested email (--users / user_email) is translated through the `emails`
+    #   map when there is a matching entry, and used as-is when there is none. The
+    #   rule is the same whether one user or several are requested: a named address
+    #   is never swapped for a different one, because nothing here says whose address
+    #   was named. An email that matches no commits yields an empty report — never
+    #   another person's data.
+    #
+    # `user` — the default git commit email(s), used when NO --users / user_email is
+    #   given (run it for yourself without --users). Every source reads its own
+    #   `user`, so git and google_calendar may hold different addresses. It is not
+    #   consulted once an address is named: pair the two with an `emails` entry
+    #   instead, which states which work email the git identity belongs to.
+    #   A malformed address is warned about and dropped; with none left, the source
+    #   is skipped for that run and listed in failed_sources.
+    # user: your.personal@email.com
+    # user:
+    #   - you@corp.com
+    #   - 12345+you@users.noreply.github.com
+    #
+    # `emails` — translate a requested email -> git commit email(s). Applied on every
+    #   path whenever that email is passed via --users / user_email. Add an entry for
+    #   yourself too if your git identity differs from the work email you pass in.
+    #   A malformed address is warned about and dropped; an entry left with none
+    #   falls back to the requested email as-is.
+    # emails:
+    #   alice@corp.com: alice.private@gmail.com
+    #   bob@corp.com:
+    #     - bob@corp.com
+    #     - 67890+bob@users.noreply.github.com
+  google_calendar:
+    # Credentials come from GOOGLE_* environment variables, not from this file.
+    #
+    # Calendar to read meeting events from. One calendar only; a list is rejected.
+    # Default: "primary". That is each reported user's own main calendar.
+    # Set this and every reported user reads the same calendar instead. Each user is
+    # still authenticated as themselves, so Google checks their access.
+    # calendar_id: "primary"
+    #
+    # `emails` must give one address per person for this source. A list is rejected.
+    #
+    # Meeting time is filtered to the working_hours block below (if set): events fully
+    # outside work hours are dropped; partial overlaps are clamped.
+
+# Optional: filter calculated time to business hours.
+# Applies to Jira, ClickUp, Linear and Google Calendar meeting time.
+# Omit this block to keep raw wall-clock time calculation.
+# Note: start_hour must be earlier than end_hour (night shifts not supported); equal
+# hours are rejected too. A shared block that breaks this is ignored with a warning,
+# leaving time unfiltered; a person's block falls back to the shared one.
+# working_hours:
+#   timezone: "Europe/Warsaw"       # IANA timezone name
+#   start_hour: "09:00"             # Work day start (HH:MM, must be quoted)
+#   end_hour: "17:00"               # Work day end (HH:MM, must be quoted)
+#   work_days: [1, 2, 3, 4, 5]      # Mon-Fri (0=Sun, 1=Mon, ..., 6=Sat)
+#   holidays_region: "pl"           # Country code for public holiday exclusion (optional)
+#
+#   # Optional: per-person overrides, keyed by the work email reports are requested for
+#   # (user_email: / user_emails:). A person inherits every key they leave out, and
+#   # anyone not listed here uses the block above unchanged.
+#   people:
+#     bob@corp.com:
+#       timezone: "America/New_York"
+#       holidays_region: "us"
+#     cara@corp.com:
+#       end_hour: "15:00"
+
+# Optional: directory that saved markdown/html reports are written to.
+# A relative path is resolved against the working directory.
+# Default: ./snitcher_reports
+# Overridden per call by output_dir:, and by output_path: for a single report.
+# output_dir: "tmp/snitcher_reports"

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.2.0]
+
+- First release published to RubyGems.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Visuality
+
+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.