@jira-report/core

Library inti untuk Jira Report: Jira client, domain logic, report generator, cache, dan configuration helpers. Dipakai baik di CLI, backend, maupun project lain yang butuh laporan progress dari Jira.

Install

Dari npm registry:

npm install @jira-report/core
# atau
yarn add @jira-report/core
# atau
pnpm add @jira-report/core
# atau
bun add @jira-report/core

Setup

1. Buat file .env

JIRA_BASE_URL=https://your-company.atlassian.net
[email protected]
JIRA_API_TOKEN=token-from-atlassian
JIRA_PROJECT_KEY=STR
JIRA_API_VERSION=3
JIRA_STORY_POINTS_FIELD=customfield_10016

Token Jira bisa dibuat di: https://id.atlassian.com/manage-profile/security/api-tokens

2. Pastikan file konfigurasi default ada

./config/status-map.json       (opsional, fallback default)
./config/progress-weights.json (opsional, fallback default)

Kalau tidak ada, package akan pakai default internal.

Usage

A. Pakai pipeline siap jalan

import { loadConfig, runGenerate } from "@jira-report/core";

const config = loadConfig();
const outputPath = await runGenerate({
  config,
  outputPath: "./reports/progress.xlsx",
  filters: {},
  useCache: true,
  refresh: false,
  perSprintSheets: false,
});

console.log("Report generated:", outputPath);

B. Pakai JiraClient secara manual

import { JiraClient } from "@jira-report/core";

const client = JiraClient.fromCredentials({
  baseUrl: "https://your-company.atlassian.net",
  email: "[email protected]",
  token: "token",
  apiVersion: "3",
});

const projects = await client.getProjects();
const boards = await client.getBoards("STR");

C. Manual config (tanpa .env)

import { runGenerate, type AppConfig } from "@jira-report/core";

const config: AppConfig = {
  jiraBaseUrl: "https://...",
  jiraEmail: "...",
  jiraApiToken: "...",
  jiraProjectKey: "STR",
  jiraApiVersion: "3",
  storyPointsField: "customfield_10016",
  statusMapPath: "./config/status-map.json",
  progressWeightsPath: "./config/progress-weights.json",
  cacheDir: "./.cache/jira",
  cacheTtlMinutes: 30,
};

await runGenerate({ config, outputPath: "./reports/progress.xlsx", filters: {}, useCache: false, refresh: true, perSprintSheets: false });

Scripts

| Command | Description | |---|---| | bun run build | Compile src/ ke dist/ dengan tsc | | bun run test | Jalankan Vitest | | bun run typecheck | Jalankan tsc --noEmit | | bun run release | Release pakai release-it |

Publish ke npm

Publish manual

1. Login ke npm:

   npm login

2. Build package:

   bun run build

3. Publish:

   npm publish

First release (v1.0.0)

Kalau ini kali pertama publish dan package.json sudah disetel ke 1.0.0, publish manual agar versi tetap 1.0.0:

cd packages/core
npm publish

npm publish akan otomatis menjalankan prepublishOnly (build). Setelah 1.0.0 terbit, rilis berikutnya bisa pakai release-it.

Publish via release-it

release-it script hanya tersedia di packages/core. Jalankan dari dalam folder tersebut, atau pakai alias root.

Penting: release-it selalu menaikkan versi. Jadi 1.0.0 akan menjadi 1.0.1 (patch), 1.1.0 (minor), atau 2.0.0 (major).

Dry-run non-interaktif (tanpa prompt):

# dari packages/core
bun run release -- patch --dry-run --ci

# dari root monorepo
bun run release:core -- patch --dry-run --ci

Rilis asli (tanpa --dry-run):

# dari packages/core
bun run release -- patch

# dari root monorepo
bun run release:core -- patch

Pilihan rilis:

# 1.0.0 -> 1.0.1
bun run release -- patch

# 1.0.0 -> 1.1.0
bun run release -- minor

# 1.0.0 -> 2.0.0
bun run release -- major

release-it akan:

1. Jalankan prepublishOnly (auto build)
2. Bump version di package.json
3. Publish @jira-report/core ke npm

Konfigurasi .release-it.json tidak melakukan git commit atau git tag otomatis, jadi setelah publish kamu perlu commit dan tag manual:

git add packages/core/package.json packages/core/CHANGELOG.md
git commit -m "chore(release): @jira-report/core v1.0.1"
git tag core-v1.0.1
git push origin master --tags

Keterangan Publish

• Package ini scoped: @jira-report/core
• publishConfig sudah disetel access: "public"
• Yang dipublish hanya isi dist/ dan README.md + package.json
• Pastikan sudah npm login sebelum release

License

MIT