@enrichlayer/el-linear 1.6.0 → 1.9.0

package/dist/utils/output.js

@@ -1,9 +1,11 @@
 import { execFileSync } from "node:child_process";
+import { dispatch as dispatchSummary, inferKindFromPayload, } from "./formatters/summary.js";
 import { logger } from "./logger.js";
 const warningBuffer = [];
 let rawMode = false;
 let jqFilter = null;
 let fieldsFilter = null;
+let outputFormat = "json";
 export function setRawMode(enabled) {
     rawMode = enabled;
 }
@@ -13,6 +15,12 @@ export function setJqFilter(filter) {
 export function setFieldsFilter(fields) {
     fieldsFilter = fields;
 }
+export function setOutputFormat(format) {
+    outputFormat = format;
+}
+export function getOutputFormat() {
+    return outputFormat;
+}
 function filterFields(obj, fields) {
     if (Array.isArray(obj)) {
         return obj.map((item) => filterFields(item, fields));
@@ -29,6 +37,15 @@ function filterFields(obj, fields) {
     }
     return obj;
 }
+/**
+ * Emit a summary-format render to stdout for the given payload. The
+ * caller (`outputSuccess`) has already applied `--raw` and `--fields`,
+ * so the value here is post-filter — no need to unwrap again.
+ */
+function emitSummary(payload) {
+    const kind = inferKindFromPayload(payload);
+    logger.info(dispatchSummary(kind, payload));
+}
 export function outputSuccess(data) {
     const warnings = drainWarnings();
     let output;
@@ -66,6 +83,13 @@ export function outputSuccess(data) {
             }
         }
     }
+    // summary format takes the post-raw / post-fields value and renders it
+    // as a human-readable block. We bypass the jq path because jq is a
+    // JSON-shape filter — it doesn't compose with text output.
+    if (outputFormat === "summary") {
+        emitSummary(output);
+        return;
+    }
     if (jqFilter) {
         const json = JSON.stringify(output);
         // Normalize common shell-escape artifacts (zsh history expansion)
@@ -87,7 +111,7 @@ export function outputSuccess(data) {
         logger.info(JSON.stringify(output, null, 2));
     }
 }
-export function outputWarning(message, _type) {
+export function outputWarning(message) {
     const messages = Array.isArray(message) ? message : [message];
     for (const msg of messages) {
         warningBuffer.push(msg);
@@ -103,6 +127,9 @@ function drainWarnings() {
 export function resetWarnings() {
     warningBuffer.length = 0;
 }
+export function resetOutputFormat() {
+    outputFormat = "json";
+}
 function outputError(error) {
     const payload = JSON.stringify({ error: error.message }, null, 2);
     // Write to stdout (same channel as success) so machine callers always

package/dist/utils/protected-ranges.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared "protected ranges" scanner — used by both
+ * `issue-reference-wrapper` and `issue-reference-extractor` so they
+ * agree on which spans of input text should be excluded from
+ * identifier processing.
+ *
+ * Why this exists: a transform/consumer pair that disagree about what
+ * counts as "protected" silently produces phantom relations or
+ * double-wrapped links. Concretely, the wrapper protects fenced code,
+ * inline code, markdown links, Slack links, angle-bracket autolinks,
+ * AND bare URLs; the extractor used to only strip fenced code, so
+ * `[click](https://x/DEV-100)` would wrap correctly but the auto-link
+ * extractor would still detect DEV-100 inside the URL and create a
+ * phantom relation. Same for `https://github.com/org/repo/DEV-100.md`.
+ *
+ * Centralising the scanner makes both consumers agree by construction.
+ */
+/** Linear identifier shape: ABC-123, EMW-1, DEV-3592. */
+export declare const IDENTIFIER_REGEX: RegExp;
+export interface ProtectedRange {
+    end: number;
+    start: number;
+}
+/**
+ * Find ranges of `text` that should NOT have identifiers processed.
+ * Covered: fenced code, inline backticks, existing markdown links,
+ * Slack links, angle-bracket autolinks, bare URLs.
+ *
+ * The returned ranges may overlap; callers only test "is this position
+ * inside any protected range" so overlap is harmless.
+ */
+export declare function findProtectedRanges(text: string): ProtectedRange[];
+export declare function isProtected(pos: number, ranges: ProtectedRange[]): boolean;

package/dist/utils/protected-ranges.js

@@ -0,0 +1,73 @@
+/**
+ * Shared "protected ranges" scanner — used by both
+ * `issue-reference-wrapper` and `issue-reference-extractor` so they
+ * agree on which spans of input text should be excluded from
+ * identifier processing.
+ *
+ * Why this exists: a transform/consumer pair that disagree about what
+ * counts as "protected" silently produces phantom relations or
+ * double-wrapped links. Concretely, the wrapper protects fenced code,
+ * inline code, markdown links, Slack links, angle-bracket autolinks,
+ * AND bare URLs; the extractor used to only strip fenced code, so
+ * `[click](https://x/DEV-100)` would wrap correctly but the auto-link
+ * extractor would still detect DEV-100 inside the URL and create a
+ * phantom relation. Same for `https://github.com/org/repo/DEV-100.md`.
+ *
+ * Centralising the scanner makes both consumers agree by construction.
+ */
+/** Linear identifier shape: ABC-123, EMW-1, DEV-3592. */
+export const IDENTIFIER_REGEX = /\b([A-Z][A-Z0-9]*-\d+)\b/g;
+const FENCED_CODE_BLOCK_REGEX = /(?:^|\n)([ \t]*)(?:```|~~~)[^\n]*\n[\s\S]*?\n\1?(?:```|~~~)(?=\n|$)/g;
+// Inline backtick spans — `EMW-258`. Markdown allows multiple backticks
+// for spans containing backticks; we keep it simple and match
+// single-backtick spans, which covers the common case.
+const INLINE_CODE_REGEX = /`[^`\n]+?`/g;
+// Existing markdown links: [text](url). Both halves protected so
+// identifiers inside the URL or the text aren't reprocessed.
+const MARKDOWN_LINK_REGEX = /\[([^\]]*)\]\(([^)]*)\)/g;
+// Existing Slack mrkdwn links: <url|text>. Both halves protected for
+// the same reason as markdown links.
+const SLACK_LINK_REGEX = /<https?:\/\/[^|>\s]+\|[^>]*>/g;
+// Angle-bracket autolinks: <https://...>
+const ANGLE_AUTOLINK_REGEX = /<[^>\s]+>/g;
+// Bare URLs in prose. We protect these so identifiers inside path
+// components (e.g. "https://github.com/foo/DEV-100") don't get
+// processed.
+const BARE_URL_REGEX = /https?:\/\/\S+/g;
+/**
+ * Find ranges of `text` that should NOT have identifiers processed.
+ * Covered: fenced code, inline backticks, existing markdown links,
+ * Slack links, angle-bracket autolinks, bare URLs.
+ *
+ * The returned ranges may overlap; callers only test "is this position
+ * inside any protected range" so overlap is harmless.
+ */
+export function findProtectedRanges(text) {
+    const ranges = [];
+    for (const re of [
+        FENCED_CODE_BLOCK_REGEX,
+        INLINE_CODE_REGEX,
+        MARKDOWN_LINK_REGEX,
+        // Slack links must be considered before generic angle-bracket
+        // autolinks — the autolink regex doesn't know about the `|label`
+        // boundary, but matchAll resets per regex so order is just for
+        // clarity here.
+        SLACK_LINK_REGEX,
+        ANGLE_AUTOLINK_REGEX,
+        BARE_URL_REGEX,
+    ]) {
+        for (const m of text.matchAll(re)) {
+            const start = m.index ?? 0;
+            ranges.push({ start, end: start + m[0].length });
+        }
+    }
+    return ranges;
+}
+export function isProtected(pos, ranges) {
+    for (const r of ranges) {
+        if (pos >= r.start && pos < r.end) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/utils/table-formatter.d.ts

@@ -1,4 +1,40 @@
 import type { LinearIssue } from "../types/linear.js";
+/**
+ * Column definition for the fixed-width text and CSV renderers.
+ * Generic over the row type `T` so the same renderers serve issues,
+ * projects, and any future resource that wants table output. The
+ * `colorize` hook receives the row so it can branch on entity-
+ * specific fields (e.g. the issue's priority or status); pass
+ * undefined to skip color.
+ */
+export interface ColumnDef<T> {
+    colorize?: (value: string, row: T) => string;
+    extract: (row: T) => string;
+    header: string;
+    key: string;
+    width: number;
+}
+/**
+ * Render `rows` as a fixed-width text table using `columns`. Generic
+ * over the row type `T` so issues, projects, and other resources
+ * share the same width-padding + colorize machinery.
+ */
+export declare function renderFixedWidthTable<T>(rows: T[], columns: ColumnDef<T>[]): string;
+/**
+ * Render `rows` as CSV using `columns`. Quotes any value containing
+ * `,` or `"` (RFC 4180-style escaping). Generic over the row type.
+ */
+export declare function renderCsv<T>(rows: T[], columns: ColumnDef<T>[]): string;
 export declare function formatTable(issues: LinearIssue[], fieldNames?: string[]): string;
 export declare function formatCsv(issues: LinearIssue[], fieldNames?: string[]): string;
+export interface MarkdownColumnDef<T> {
+    align?: "left" | "right";
+    extract: (row: T) => string;
+    header: string;
+}
+/**
+ * Render `rows` as a markdown table using `columns`. Generic over
+ * the row type. Escapes `|` and newlines in cell values.
+ */
+export declare function renderMarkdownTable<T>(rows: T[], columns: MarkdownColumnDef<T>[]): string;
 export declare function formatMarkdown(issues: LinearIssue[], fieldNames?: string[]): string;

package/dist/utils/table-formatter.js

@@ -129,39 +129,54 @@ function pad(str, width) {
     const truncated = truncate(str, width);
     return truncated + " ".repeat(Math.max(0, width - truncated.length));
 }
-export function formatTable(issues, fieldNames) {
-    const columnKeys = fieldNames ?? DEFAULT_COLUMNS;
-    const columns = columnKeys
-        .map((key) => ALL_COLUMNS[key])
-        .filter((col) => col !== undefined);
+/**
+ * Render `rows` as a fixed-width text table using `columns`. Generic
+ * over the row type `T` so issues, projects, and other resources
+ * share the same width-padding + colorize machinery.
+ */
+export function renderFixedWidthTable(rows, columns) {
     if (columns.length === 0) {
         return "No valid columns specified.";
     }
     const header = columns.map((col) => pad(col.header, col.width)).join("  ");
     const separator = columns.map((col) => "─".repeat(col.width)).join("──");
-    const rows = issues.map((issue) => columns
+    const body = rows.map((row) => columns
         .map((col) => {
-        const padded = pad(col.extract(issue), col.width);
-        return col.colorize ? col.colorize(padded, issue) : padded;
+        const padded = pad(col.extract(row), col.width);
+        return col.colorize ? col.colorize(padded, row) : padded;
     })
         .join("  "));
-    return [header, separator, ...rows].join("\n");
+    return [header, separator, ...body].join("\n");
 }
-export function formatCsv(issues, fieldNames) {
-    const columnKeys = fieldNames ?? DEFAULT_COLUMNS;
-    const columns = columnKeys
-        .map((key) => ALL_COLUMNS[key])
-        .filter((col) => col !== undefined);
+/**
+ * Render `rows` as CSV using `columns`. Quotes any value containing
+ * `,` or `"` (RFC 4180-style escaping). Generic over the row type.
+ */
+export function renderCsv(rows, columns) {
     const header = columns.map((col) => col.header).join(",");
-    const rows = issues.map((issue) => columns
+    const body = rows.map((row) => columns
         .map((col) => {
-        const value = col.extract(issue);
+        const value = col.extract(row);
         return value.includes(",") || value.includes('"')
             ? `"${value.replace(/"/g, '""')}"`
             : value;
     })
         .join(","));
-    return [header, ...rows].join("\n");
+    return [header, ...body].join("\n");
+}
+export function formatTable(issues, fieldNames) {
+    const columnKeys = fieldNames ?? DEFAULT_COLUMNS;
+    const columns = columnKeys
+        .map((key) => ALL_COLUMNS[key])
+        .filter((col) => col !== undefined);
+    return renderFixedWidthTable(issues, columns);
+}
+export function formatCsv(issues, fieldNames) {
+    const columnKeys = fieldNames ?? DEFAULT_COLUMNS;
+    const columns = columnKeys
+        .map((key) => ALL_COLUMNS[key])
+        .filter((col) => col !== undefined);
+    return renderCsv(issues, columns);
 }
 // ── Markdown formatting ────────────────────────────────────────
 const STATUS_MD = {
@@ -234,16 +249,23 @@ const MD_COLUMNS = {
 function escapeMarkdownCell(str) {
     return str.replace(/\|/g, "\\|").replace(/\n/g, " ");
 }
-export function formatMarkdown(issues, fieldNames) {
-    const columnKeys = fieldNames ?? DEFAULT_COLUMNS;
-    const columns = columnKeys
-        .map((key) => MD_COLUMNS[key])
-        .filter((col) => col !== undefined);
+/**
+ * Render `rows` as a markdown table using `columns`. Generic over
+ * the row type. Escapes `|` and newlines in cell values.
+ */
+export function renderMarkdownTable(rows, columns) {
     if (columns.length === 0) {
         return "No valid columns specified.";
     }
     const header = `| ${columns.map((col) => col.header).join(" | ")} |`;
     const divider = `| ${columns.map((col) => (col.align === "right" ? "---:" : "---")).join(" | ")} |`;
-    const rows = issues.map((issue) => `| ${columns.map((col) => escapeMarkdownCell(col.extract(issue))).join(" | ")} |`);
-    return [header, divider, ...rows].join("\n");
+    const body = rows.map((row) => `| ${columns.map((col) => escapeMarkdownCell(col.extract(row))).join(" | ")} |`);
+    return [header, divider, ...body].join("\n");
+}
+export function formatMarkdown(issues, fieldNames) {
+    const columnKeys = fieldNames ?? DEFAULT_COLUMNS;
+    const columns = columnKeys
+        .map((key) => MD_COLUMNS[key])
+        .filter((col) => col !== undefined);
+    return renderMarkdownTable(issues, columns);
 }

package/dist/utils/validators.d.ts

@@ -9,6 +9,14 @@ export declare function parsePositiveInt(value: string, flagName: string): numbe
 export declare function validatePriority(value: string): number;
 export declare function validateHexColor(value: string): string;
 export declare function validateIsoDate(value: string): string;
-export declare function splitList(value: string): string[];
+/**
+ * Split a comma-separated list into trimmed, non-empty items.
+ *
+ * Accepts `undefined` so call sites can pipe through commander's
+ * optional flag values without an explicit truthy guard. `false`
+ * (commander's representation of `--no-foo`) and empty string both
+ * resolve to `[]`.
+ */
+export declare function splitList(value: string | undefined | null | false): string[];
 export declare function parsePriorityFilter(value: string): number[];
 export declare const PRIORITY_LABELS: Record<number, string>;

package/dist/utils/validators.js

@@ -42,7 +42,17 @@ export function validateIsoDate(value) {
     }
     return value;
 }
+/**
+ * Split a comma-separated list into trimmed, non-empty items.
+ *
+ * Accepts `undefined` so call sites can pipe through commander's
+ * optional flag values without an explicit truthy guard. `false`
+ * (commander's representation of `--no-foo`) and empty string both
+ * resolve to `[]`.
+ */
 export function splitList(value) {
+    if (!value)
+        return [];
     return value
         .split(",")
         .map((s) => s.trim())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.6.0",
+  "version": "1.9.0",
   "description": "A pragmatic CLI for Linear.app — deterministic team/label/member resolution, structured issue validation, configurable term enforcement, and a GraphQL escape hatch.",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",