@enrichlayer/el-linear 1.43.0 → 1.44.0

package/dist/config/intake-decision-validation.js

@@ -10,6 +10,14 @@
  * OPT-IN by design. el-linear is open source, so the gate is dormant unless a
  * workspace config sets `validation.intakeDecisionGate` to `"warn"` or
  * `"block"`.
+ *
+ * DEV-7074: the parser accepts the markdown an author actually types — any
+ * list marker (`-`, `*`, `+`, `1.`) and bolded or italicized labels with the
+ * colon inside (`**Needed:**`) or outside (`**Needed**:`) the emphasis run.
+ * When a field genuinely fails, the diagnostic names WHICH failure it is:
+ * an unreadable line, an absent field, an empty value, a placeholder, or a
+ * present-but-unjudged value. Reporting a formatting mismatch as empty content
+ * sent authors to rewrite prose that was already correct.
  */
 import { extractField, stripFencedCodeBlocks } from "../utils/extract-field.js";
 import { loadConfig } from "./config.js";
@@ -34,25 +42,116 @@ const FIELD_DEFINITIONS = [
     { key: "placement", label: "Placement" },
     { key: "decision", label: "Decision" },
 ];
-const FIELD_LINE = /^\s*(?:[-*+]\s+|\d+[.)]\s+)?(?:\*\*)?(Needed|Worth doing|Existing work|Owner|Placement|Decision)(?:\*\*)?\s*:\s*(.*?)\s*$/gim;
+/**
+ * A field line, split at its FIRST colon: an optional list marker or ordinal,
+ * the label part, then the value part. Emphasis markers are deliberately not
+ * described here — the label and value are normalized separately, because
+ * markdown lets the colon fall either inside (`**Needed:**`) or outside
+ * (`**Needed**:`) the emphasis run (DEV-7074).
+ */
+const FIELD_LINE = /^[ \t]*(?:[-*+][ \t]+|\d+[.)][ \t]+)?([^:\n]*):(.*)$/;
+/** Leading / trailing markdown emphasis run (`**`, `__`, `*`, `_`). */
+const LEADING_EMPHASIS = /^[*_]{1,3}\s*/;
+const TRAILING_EMPHASIS = /\s*[*_]{1,3}$/;
+/** A value entirely wrapped in one emphasis run, e.g. `**PROCEED**`. */
+const WRAPPED_IN_EMPHASIS = /^([*_]{1,3})([^*_].*?)\1$/;
+/**
+ * A paired inline emphasis run at a token boundary. The boundaries are
+ * load-bearing: a literal underscore in `PRO_CEED` or `customer_support` is
+ * content, not markdown, and must not disappear during semantic validation.
+ */
+const INLINE_EMPHASIS = /(^|[^\p{L}\p{N}])([*_]{1,3})(?=\S)(.+?\S)\2(?=$|[^\p{L}\p{N}])/gu;
 const PLACEHOLDER = /^(?:tbd|todo|unknown|n\/?a|none|unsure|not decided|-)\.?$/i;
 const NON_SPECIFIC = /^(?:yes|no)$/i;
 const AFFIRMATIVE_WITH_REASON = /^yes\s*(?:[-—:;,]|because)\s*(\S.{2,})$/i;
+function labelOf(key) {
+    return FIELD_DEFINITIONS.find((field) => field.key === key)?.label ?? key;
+}
 function normalizedKey(label) {
-    switch (label.toLowerCase()) {
-        case "needed":
-            return "needed";
-        case "worth doing":
-            return "worth";
-        case "existing work":
-            return "existing";
-        case "owner":
-            return "owner";
-        case "placement":
-            return "placement";
-        default:
-            return "decision";
+    const normalized = label.toLowerCase().trim().replace(/\s+/g, " ");
+    return (FIELD_DEFINITIONS.find((field) => field.label.toLowerCase() === normalized)
+        ?.key ?? null);
+}
+/** Strip the emphasis markers wrapping a label, e.g. `**Needed**` -> `Needed`. */
+function stripLabelEmphasis(raw) {
+    const trimmed = raw.trim();
+    const opened = LEADING_EMPHASIS.test(trimmed);
+    const closed = TRAILING_EMPHASIS.test(trimmed);
+    return {
+        label: trimmed.replace(LEADING_EMPHASIS, "").replace(TRAILING_EMPHASIS, ""),
+        opensEmphasis: opened && !closed,
+    };
+}
+function normalizeFieldValue(raw, labelOpensEmphasis) {
+    let value = raw.trim();
+    if (labelOpensEmphasis) {
+        // The emphasis run heading the value closes the label's bold, it is not
+        // part of the value: `* **Needed:** Yes — …`.
+        value = value.replace(LEADING_EMPHASIS, "").trim();
+    }
+    const wrapped = value.match(WRAPPED_IN_EMPHASIS);
+    return (wrapped?.[2] ?? value).trim();
+}
+/**
+ * The value with inline emphasis removed, used for the SEMANTIC checks only.
+ * `- Decision: **PROCEED**` and `- Needed: **Yes** — …` are the same judgments
+ * as their unemphasized forms. Diagnostics report the parsed value, which
+ * normalizes a whole-value wrapper but preserves emphasis within longer prose.
+ */
+function withoutEmphasis(value) {
+    let normalized = value;
+    let previous;
+    do {
+        previous = normalized;
+        normalized = normalized.replace(INLINE_EMPHASIS, "$1$3");
+    } while (normalized !== previous);
+    return normalized.trim();
+}
+function parseFieldLine(line) {
+    const match = line.match(FIELD_LINE);
+    if (!match)
+        return null;
+    const { label, opensEmphasis } = stripLabelEmphasis(match[1] ?? "");
+    const key = normalizedKey(label);
+    if (key === null)
+        return null;
+    return { key, value: normalizeFieldValue(match[2] ?? "", opensEmphasis) };
+}
+/**
+ * Find a line that names `label` but did not parse as `Label: value` — a
+ * formatting failure, not absent content. Reported as `unparsed-field` so the
+ * author fixes the line instead of writing a field they already wrote.
+ */
+function findUnparsedLine(lines, label) {
+    // Built from FIELD_DEFINITIONS' fixed labels (no regex metacharacters).
+    const names = new RegExp(`^[ \\t]*(?:[-*+][ \\t]+|\\d+[.)][ \\t]+)?[*_]{0,3}${label}\\b`, "i");
+    for (const line of lines) {
+        if (names.test(line) && parseFieldLine(line) === null)
+            return line.trim();
+    }
+    return null;
+}
+function classifyValue(key, value) {
+    if (value.length === 0)
+        return "empty";
+    const probe = withoutEmphasis(value);
+    if (probe.length === 0)
+        return "empty";
+    if (PLACEHOLDER.test(probe))
+        return "placeholder";
+    if (key === "needed" || key === "worth") {
+        const match = probe.match(AFFIRMATIVE_WITH_REASON);
+        if (!match)
+            return "no-judgment";
+        return PLACEHOLDER.test(match[1]?.trim() ?? "")
+            ? "placeholder-reason"
+            : null;
     }
+    // Measure the parsed value rather than the semantic probe so removing inline
+    // emphasis markers cannot make substantive content look artificially short.
+    if (value.length < 3 || NON_SPECIFIC.test(probe))
+        return "non-specific";
+    return null;
 }
 export function evaluateIntakeDecision(description, headers = DEFAULT_INTAKE_SECTION_HEADERS) {
     let section = null;
@@ -69,28 +168,36 @@ export function evaluateIntakeDecision(description, headers = DEFAULT_INTAKE_SEC
     }
     // A template/example fence is not an operative decision record. Remove all
     // fenced examples before matching so copied guidance cannot satisfy intake.
-    const operativeSection = stripFencedCodeBlocks(section);
+    const lines = stripFencedCodeBlocks(section).split("\n");
     const values = new Map();
-    for (const match of operativeSection.matchAll(FIELD_LINE)) {
-        const key = normalizedKey(match[1] ?? "");
-        if (values.has(key)) {
+    for (const [index, line] of lines.entries()) {
+        const parsed = parseFieldLine(line);
+        if (!parsed)
+            continue;
+        if (values.has(parsed.key)) {
             return {
                 ok: false,
                 reason: "duplicate-field",
-                field: FIELD_DEFINITIONS.find((field) => field.key === key)?.label ?? key,
+                field: labelOf(parsed.key),
             };
         }
-        values.set(key, { value: match[2]?.trim() ?? "", index: match.index });
+        values.set(parsed.key, { value: parsed.value, index });
     }
     let previousIndex = -1;
     for (const definition of FIELD_DEFINITIONS) {
         const entry = values.get(definition.key);
         if (!entry) {
-            return {
-                ok: false,
-                reason: "missing-field",
-                field: definition.label,
-            };
+            // Distinguish "the field is absent" from "the field is there but its
+            // line does not parse" — different authoring fixes (DEV-7074).
+            const unparsed = findUnparsedLine(lines, definition.label);
+            return unparsed === null
+                ? { ok: false, reason: "missing-field", field: definition.label }
+                : {
+                    ok: false,
+                    reason: "unparsed-field",
+                    field: definition.label,
+                    line: unparsed,
+                };
         }
         if (entry.index < previousIndex) {
             return {
@@ -101,40 +208,55 @@ export function evaluateIntakeDecision(description, headers = DEFAULT_INTAKE_SEC
         }
         previousIndex = entry.index;
     }
-    for (const key of ["needed", "worth"]) {
+    for (const key of [
+        "needed",
+        "worth",
+        "existing",
+        "owner",
+        "placement",
+    ]) {
         const value = values.get(key)?.value ?? "";
-        const match = value.match(AFFIRMATIVE_WITH_REASON);
-        const reason = match?.[1]?.trim() ?? "";
-        if (!match || PLACEHOLDER.test(reason)) {
+        const problem = classifyValue(key, value);
+        if (problem !== null) {
             return {
                 ok: false,
                 reason: "invalid-field",
-                field: key === "needed" ? "Needed" : "Worth doing",
-            };
-        }
-    }
-    for (const key of ["existing", "owner", "placement"]) {
-        const value = values.get(key)?.value ?? "";
-        if (value.length < 3 ||
-            PLACEHOLDER.test(value) ||
-            NON_SPECIFIC.test(value)) {
-            return {
-                ok: false,
-                reason: "invalid-field",
-                field: key === "existing"
-                    ? "Existing work"
-                    : key === "owner"
-                        ? "Owner"
-                        : "Placement",
+                field: labelOf(key),
+                problem,
+                value,
             };
         }
     }
     const decision = values.get("decision")?.value ?? "";
-    if (!/^proceed$/i.test(decision)) {
+    if (!/^proceed$/i.test(withoutEmphasis(decision))) {
         return { ok: false, reason: "not-proceeding", decision };
     }
     return { ok: true, header: matchedHeader };
 }
+/** Quote what the author actually wrote, bounded so a long line stays readable. */
+function quote(text, limit = 80) {
+    const single = text.replace(/\s+/g, " ").trim();
+    return single.length > limit ? `${single.slice(0, limit - 1)}…` : single;
+}
+/**
+ * Name the ACTUAL failure. A message that blames content for a formatting
+ * mismatch sends the author to rewrite prose that was already correct
+ * (DEV-7074), so each problem gets its own remedy.
+ */
+function describeFieldProblem(field, problem, value) {
+    switch (problem) {
+        case "empty":
+            return `The intake field "${field}" parsed, but has no content after the label.`;
+        case "placeholder":
+            return `The intake field "${field}" is the placeholder "${quote(value)}"; record a real value.`;
+        case "non-specific":
+            return `The intake field "${field}" reads "${quote(value)}", which is too short or too generic to be a specific answer.`;
+        case "no-judgment":
+            return `The intake field "${field}" reads "${quote(value)}" — the content is there, but it is not an explicit "Yes — <reason>" judgment.`;
+        case "placeholder-reason":
+            return `The intake field "${field}" says Yes but gives the placeholder reason "${quote(value)}"; record the real reason.`;
+    }
+}
 export function formatIntakeDecisionBlock(opts) {
     const { evaluation } = opts;
     let reason;
@@ -143,7 +265,10 @@ export function formatIntakeDecisionBlock(opts) {
             reason = `Issue description has no intake section (looked for: ${opts.headers.join(", ")}).`;
             break;
         case "missing-field":
-            reason = `The intake decision is missing the "${evaluation.field}" field.`;
+            reason = `The intake decision is missing the "${evaluation.field}" field — no line records it.`;
+            break;
+        case "unparsed-field":
+            reason = `The intake decision's "${evaluation.field}" line is not in "${evaluation.field}: <value>" form, so it was not read as a field: "${quote(evaluation.line)}". This is a formatting mismatch, not missing content — the label must be followed by a colon. Bolded labels are accepted in either form (\`- **${evaluation.field}:** <value>\` or \`- **${evaluation.field}**: <value>\`).`;
             break;
         case "duplicate-field":
             reason = `The intake decision repeats the "${evaluation.field}" field; record one unambiguous value.`;
@@ -152,7 +277,7 @@ export function formatIntakeDecisionBlock(opts) {
             reason = `The intake fields are out of order at "${evaluation.field}".`;
             break;
         case "invalid-field":
-            reason = `The intake field "${evaluation.field}" is empty, a placeholder, or lacks an explicit yes-and-reason judgment.`;
+            reason = describeFieldProblem(evaluation.field, evaluation.problem, evaluation.value);
             break;
         case "not-proceeding":
             reason = `The intake decision is "${evaluation.decision || "empty"}", not PROCEED.`;

package/dist/config/pin-hint.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Non-blocking repo/profile mismatch hint (DEV-7277).
+ *
+ * On write commands (`issues create`, `comments create`) a user who works
+ * across multiple Linear workspaces can silently write into the wrong one: the
+ * machine-global `active-profile` marker is whatever they last `profile use`d,
+ * and it applies to every repo that hasn't pinned a profile. This prints a
+ * ONE-LINE hint to stderr when — and only when — the active profile came from
+ * that bare global marker AND the current repo has no pin, nudging the user to
+ * `el-linear profile pin`.
+ *
+ * It NEVER blocks the command and NEVER writes to stdout (that stays reserved
+ * for the machine-parseable JSON envelope). It is suppressed by `--quiet` and
+ * by the `EL_LINEAR_NO_PIN_HINT` opt-out.
+ */
+import { type RepoLinearProfile } from "./repo-profile.js";
+export interface PinHintDeps {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    /** True when `--profile` was passed for this invocation. */
+    hasProfileFlag: boolean;
+    /** Whether `--quiet` is active. */
+    isQuiet: () => boolean;
+    /** Raw `active-profile` marker content (bypasses the flag/env layers). */
+    readMarker: () => string | null;
+    /** Repo→profile pin lookup for `cwd`. */
+    resolveRepoPin: (cwd: string) => RepoLinearProfile | null;
+    /** Sink for the one-line hint (stderr in production). */
+    write: (message: string) => void;
+}
+/**
+ * Emit the mismatch hint when applicable. Returns true when a hint was written
+ * (for tests). All decision inputs are injectable so the trigger/suppression
+ * matrix can be unit-tested without git, env, or process state.
+ */
+export declare function maybeEmitPinMismatchHint(deps: Pick<PinHintDeps, "hasProfileFlag"> & Partial<PinHintDeps>): boolean;

package/dist/config/pin-hint.js

@@ -0,0 +1,64 @@
+/**
+ * Non-blocking repo/profile mismatch hint (DEV-7277).
+ *
+ * On write commands (`issues create`, `comments create`) a user who works
+ * across multiple Linear workspaces can silently write into the wrong one: the
+ * machine-global `active-profile` marker is whatever they last `profile use`d,
+ * and it applies to every repo that hasn't pinned a profile. This prints a
+ * ONE-LINE hint to stderr when — and only when — the active profile came from
+ * that bare global marker AND the current repo has no pin, nudging the user to
+ * `el-linear profile pin`.
+ *
+ * It NEVER blocks the command and NEVER writes to stdout (that stays reserved
+ * for the machine-parseable JSON envelope). It is suppressed by `--quiet` and
+ * by the `EL_LINEAR_NO_PIN_HINT` opt-out.
+ */
+import { getQuietMode } from "../utils/output.js";
+import { isSafeProfileName, readActiveProfileMarker } from "./paths.js";
+import { resolveRepoLinearProfile, } from "./repo-profile.js";
+const ENV_OPT_IN_VALUES = new Set(["1", "true", "yes", "on"]);
+/** True only when `env[name]` is an explicit opt-in value (not `0`/`false`). */
+function isEnvOptIn(name, env) {
+    const raw = env[name]?.trim().toLowerCase();
+    return raw !== undefined && ENV_OPT_IN_VALUES.has(raw);
+}
+/**
+ * Emit the mismatch hint when applicable. Returns true when a hint was written
+ * (for tests). All decision inputs are injectable so the trigger/suppression
+ * matrix can be unit-tested without git, env, or process state.
+ */
+export function maybeEmitPinMismatchHint(deps) {
+    const env = deps.env ?? process.env;
+    const cwd = deps.cwd ?? process.cwd();
+    const isQuiet = deps.isQuiet ?? getQuietMode;
+    const readMarker = deps.readMarker ?? (() => readActiveProfileMarker());
+    const resolveRepoPin = deps.resolveRepoPin ?? ((c) => resolveRepoLinearProfile(c));
+    const write = deps.write ?? ((m) => process.stderr.write(`${m}\n`));
+    // Suppressed contexts — every one of these means the hint would be noise.
+    if (isQuiet())
+        return false;
+    if (isEnvOptIn("EL_LINEAR_NO_PIN_HINT", env))
+        return false;
+    // Came from `--profile` — the user was explicit.
+    if (deps.hasProfileFlag)
+        return false;
+    // Came from `$EL_LINEAR_PROFILE` — also explicit.
+    if ((env.EL_LINEAR_PROFILE ?? "").trim())
+        return false;
+    // Repo already has an effective pin — nothing to nudge. Startup ignores
+    // unsafe names, so the hint must apply the same predicate or a bad pin would
+    // suppress the warning while the write falls through to the global marker.
+    const pin = resolveRepoPin(cwd);
+    if (pin && isSafeProfileName(pin.profile))
+        return false;
+    // Only fire when the profile came from the BARE global marker. No marker =
+    // legacy single-profile default; that user hasn't opted into workspaces at
+    // all, so the nudge would be premature.
+    const marker = readMarker();
+    if (!marker)
+        return false;
+    write(`el-linear: writing with the machine-global active profile "${marker}" — this repo has no pinned workspace. ` +
+        "If it belongs to a specific workspace, pin it: `el-linear profile pin`. " +
+        "(silence this: EL_LINEAR_NO_PIN_HINT=1)");
+    return true;
+}

package/dist/config/repo-profile.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Repo-aware Linear-profile resolution (DEV-7277).
+ *
+ * el-linear supports multiple named profiles (one Linear workspace each). When
+ * a user works across several workspaces the machine-global `active-profile`
+ * marker is a foot-gun: whichever workspace was last `profile use`d becomes the
+ * default for EVERY repo, so a write lands in the wrong workspace.
+ *
+ * This module lets a repo PIN the profile it belongs to, read from two on-disk
+ * sources in precedence order:
+ *   1. Repo-root `.el-git.json`: `{ "linearProfile": "<name>" }`.
+ *   2. `${XDG_CONFIG_HOME:-~/.config}/el-git/linear-profiles.json`:
+ *      `{ "profiles": { "owner/repo": "<name>", "owner/*": "<name>" } }` — keys
+ *      are the origin remote's `owner/repo`; an exact key wins over the
+ *      `owner/*` wildcard.
+ *
+ * ── SHARED CROSS-TOOL CONTRACT — DO NOT DRIFT ────────────────────────────────
+ * The file names, shapes, and precedence here are the SAME contract el-git
+ * (DEV-6465) and el-session (DEV-7131) already read/write via the internal
+ * `@enrichlayer/cli-package-info` module (`resolveRepoLinearProfile`). el-linear
+ * is a standalone MIT package published to public npm; cli-package-info is
+ * published only to an internal GitLab registry, so depending on it would break
+ * public installs. Instead this file re-implements the EXACT same formats and
+ * precedence. The filename stays `.el-git.json` (NOT a new `.el-linear` file) on
+ * purpose — it is the established shared location el-session already reads. If
+ * you change anything here, change the canonical impl at
+ * `tools/cli/cli-package-info/src/index.cjs` in lock-step or the tools silently
+ * disagree about which workspace a repo belongs to.
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * Trust note (inherited from the shared contract): the repo-local file is read
+ * from whatever repo you `cd` into, including an untrusted clone. Blast radius
+ * is bounded to selecting a profile NAME — worst case is a wrong-workspace
+ * lookup or a rejected name, never code execution. Callers still validate the
+ * resolved name with `isSafeProfileName` before it reaches any path join.
+ */
+/** Repo-local pin file, at the git repo root. Shared with el-git/el-session. */
+export declare const LINEAR_PROFILE_REPO_FILE = ".el-git.json";
+/** Global pin table filename, under `<config>/el-git/`. */
+export declare const LINEAR_PROFILE_USER_CONFIG = "linear-profiles.json";
+/** Where the resolved pin came from. Mirrors the shared contract's `source`. */
+export type RepoProfileSource = "repo-file" | "user-config";
+export interface RepoLinearProfile {
+    profile: string;
+    source: RepoProfileSource;
+}
+/**
+ * Injected I/O seam so resolution is unit-testable without a real git repo or
+ * tmpdirs — mirrors the `ProfileFsOps` pattern in `paths.ts` and the `ops`
+ * injection in the canonical cli-package-info impl.
+ */
+export interface RepoProfileOps {
+    existsSync: (p: string) => boolean;
+    readFileSync: (p: string) => string;
+    /** Git repo root for `cwd`, or null when not inside a repo. */
+    repoRoot: (cwd: string) => string | null;
+    /** Origin remote parsed to `owner/repo`, or null when unavailable. */
+    originFullpath: (cwd: string) => string | null;
+}
+export interface ResolveRepoProfileOptions {
+    ops?: Partial<RepoProfileOps>;
+    env?: NodeJS.ProcessEnv;
+    /** Called with the offending file path when a config JSON is malformed. */
+    onMalformedConfig?: (filePath: string) => void;
+}
+/** `${XDG_CONFIG_HOME:-~/.config}/el-git`. Env-injectable for tests. */
+export declare function linearProfileConfigDir(env?: NodeJS.ProcessEnv): string;
+export declare function globalPinTablePath(env?: NodeJS.ProcessEnv): string;
+export declare function parseGitRemoteFullpath(url: string | null | undefined): string | null;
+/** Real git/fs implementations. Overridden per-field in tests. */
+export declare function defaultRepoProfileOps(): RepoProfileOps;
+/**
+ * Resolve the profile a repo is pinned to, or null when it has no pin.
+ * Repo-local `.el-git.json` wins over the global `owner/repo` table; within the
+ * table an exact key wins over the `owner/*` wildcard.
+ */
+export declare function resolveRepoLinearProfile(cwd?: string, opts?: ResolveRepoProfileOptions): RepoLinearProfile | null;
+/**
+ * Merge `{ linearProfile: name }` into an existing `.el-git.json` body,
+ * preserving every other key. `existing` is the current file text (or null when
+ * the file is absent). Returns the new file text (2-space, trailing newline).
+ */
+export declare function applyRepoLocalPin(existing: string | null, name: string): string;
+/**
+ * Remove the `linearProfile` key from an existing `.el-git.json` body,
+ * preserving other keys. Returns the new file text, or null when the file
+ * should be deleted (it held only the pin / was absent / becomes empty).
+ */
+export declare function removeRepoLocalPin(existing: string | null): string | null;
+/**
+ * Merge `profiles[fullpath] = name` into the global pin table body, preserving
+ * every other entry. Returns the new file text (2-space, trailing newline).
+ */
+export declare function applyGlobalPin(existing: string | null, fullpath: string, name: string): string;
+/**
+ * Remove an exact `owner/repo` entry from the global pin table. Preserves
+ * wildcard entries and unrelated top-level keys. Returns null only when the
+ * file is absent or becomes empty after removal.
+ */
+export declare function removeGlobalPin(existing: string | null, fullpath: string): string | null;