@decibelsystems/tools 2.2.0-beta.0 → 3.1.0

package/dist/domain/issueCodec.js

@@ -0,0 +1,308 @@
+// ============================================================================
+// Issue codec — EPIC-0038 Phase 3
+// ============================================================================
+// Translates between on-disk records and the canonical Issue model. This is the
+// only place that knows there are two formats.
+//
+// Two rules shape the whole file:
+//
+// 1. DECODE IS LOSSLESS. Every frontmatter key survives a decode/encode round
+//    trip, whether or not the model has a field for it. Records in this store
+//    carry keys no interface declares — `repo`, `closed_reason`, `degraded`,
+//    `source`, `projectId` alongside `project` — and a codec that emitted only
+//    the fields it recognized would silently delete them on the first write.
+//    The precedent is real: update_issue once rewrote markdown records as bare
+//    YAML and dropped the delimiters, the heading and the body.
+//
+// 2. THE BODY MIRROR IS OUTPUT, NEVER INPUT. Markdown records repeat status and
+//    severity in the body as `**Status:** x` for human readers. Decode ignores
+//    those lines entirely and reads frontmatter; encode regenerates them from
+//    the model. That asymmetry is the point — it makes the drift that hit
+//    sixteen records structurally impossible rather than merely fixed. There is
+//    no code path that can write a mirror disagreeing with its frontmatter.
+// ============================================================================
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { isUid, normalizeStatus, } from './issue.js';
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+/** Keys the model owns. Everything else is preserved verbatim in raw.data. */
+const MODEL_KEYS = new Set([
+    'uid',
+    'id',
+    'title',
+    'status',
+    'severity',
+    'priority',
+    'assignee',
+    'team',
+    'tags',
+    'epic_id',
+    'epicId',
+    'project',
+    'description',
+    'details',
+    'resolution',
+    'created_at',
+    'updated_at',
+    'closed_at',
+]);
+function normalizeTags(v) {
+    if (!Array.isArray(v))
+        return undefined;
+    const tags = v.filter((t) => typeof t === 'string' && t.trim() !== '');
+    return tags.length > 0 ? tags : undefined;
+}
+function str(v) {
+    return typeof v === 'string' && v.trim() !== '' ? v : undefined;
+}
+/**
+ * Split a bare-YAML record into its YAML head and any markdown tail at column 0.
+ *
+ * The column-0 anchor is load-bearing and must not gain `\s*`: headings indented
+ * inside a `description:` block scalar are body text, not a tail, and matching
+ * them would truncate the record at parse time. Phase 2 verified no record in
+ * the store relies on the difference, but nothing else pins it, so it is pinned
+ * by test here.
+ */
+export function splitBareYaml(content) {
+    const lines = content.split('\n');
+    const idx = lines.findIndex((l) => /^#{1,6}\s/.test(l));
+    if (idx < 0)
+        return { head: content, tail: '' };
+    return { head: lines.slice(0, idx).join('\n'), tail: lines.slice(idx).join('\n') };
+}
+/**
+ * Prose under `## Details`, which is where the markdown format keeps the body.
+ *
+ * This used to stop at the next `##` heading of any kind, which quietly made
+ * the format unable to hold a structured issue. Authors write `## Problem`,
+ * `## Root Cause`, `## Fix` — 44 records in this store did, and every one read
+ * back truncated at the first of them, in two cases from 107 characters to 30.
+ *
+ * Only ONE trailing section is not the author's: `## Resolution`, which
+ * encodeIssue regenerates from `issue.resolution` and which decode reads from
+ * frontmatter. Including it here would duplicate it into details and then
+ * re-append it on every write. Everything else belongs to the body.
+ *
+ * The trailing occurrence is the one stripped, not the first — an issue whose
+ * prose discusses a resolution mid-body keeps it.
+ */
+function extractDetails(body) {
+    const m = body.match(/^##\s+Details\s*\n([\s\S]*)$/m);
+    if (!m)
+        return undefined;
+    let rest = m[1];
+    const headings = [...rest.matchAll(/\n##\s+Resolution\s*(?:\n|$)/g)];
+    const last = headings[headings.length - 1];
+    if (last?.index !== undefined)
+        rest = rest.slice(0, last.index);
+    return rest.trim() || undefined;
+}
+export function decodeIssue(filename, content) {
+    const warnings = [];
+    const fm = FRONTMATTER_RE.exec(content);
+    let data;
+    let body;
+    let format;
+    if (fm) {
+        format = 'md';
+        body = fm[2];
+        try {
+            data = parseYaml(fm[1]) ?? {};
+        }
+        catch (err) {
+            data = {};
+            warnings.push(`frontmatter did not parse: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    else {
+        format = 'yaml';
+        const split = splitBareYaml(content);
+        body = split.tail;
+        if (split.tail.trim()) {
+            // Phase 2 repaired every instance of this. A new one means a writer is
+            // appending markdown to bare YAML again.
+            warnings.push('bare-YAML record has a markdown tail — a writer is appending prose outside the YAML');
+        }
+        try {
+            data = parseYaml(split.head) ?? {};
+        }
+        catch (err) {
+            data = {};
+            warnings.push(`YAML did not parse: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (typeof data !== 'object' || data === null) {
+        data = {};
+        warnings.push('record did not parse to an object');
+    }
+    // ---- id: frontmatter ISS-NNNN, else the filename ------------------------
+    const fmId = str(data.id);
+    const id = (fmId && /^ISS-\d+$/i.test(fmId) ? fmId.toUpperCase() : undefined) ??
+        filename.match(/^(ISS-\d+)/i)?.[1]?.toUpperCase() ??
+        fmId ??
+        filename.replace(/\.(md|ya?ml)$/i, '');
+    // ---- title: frontmatter wins, then the heading, then the filename -------
+    //
+    // Frontmatter first, because the writer puts a title there ONLY when the
+    // body cannot hold it — no heading at all, or a title containing a newline,
+    // which a `# heading` truncates at the line break. Reading the heading first
+    // meant a multi-line title came back as its first line, from a record whose
+    // frontmatter held the whole thing: "first line\nsecond line" read back as
+    // "first line", with create_issue reporting success.
+    //
+    // Preferring frontmatter cannot regress a record that predates this, because
+    // the writer never emitted both: `title` went to frontmatter exactly when
+    // there was no heading to compete with it.
+    const heading = body.match(/^#\s+(.+)$/m)?.[1]?.trim();
+    const fmTitle = str(data.title);
+    const title = fmTitle ?? heading ?? filename.replace(/\.(md|ya?ml)$/i, '');
+    if (!heading && !fmTitle) {
+        warnings.push('no title in heading or frontmatter — fell back to the filename');
+    }
+    // ---- status: the whole reason this codec exists -------------------------
+    const norm = normalizeStatus(data.status);
+    if (norm.unrecognized) {
+        warnings.push(`unrecognized status ${JSON.stringify(data.status)} — read as ${norm.status}`);
+    }
+    else if (norm.normalizedFrom) {
+        warnings.push(`status ${JSON.stringify(norm.normalizedFrom)} normalized to ${norm.status}`);
+    }
+    const uid = isUid(data.uid) ? data.uid : undefined;
+    if (data.uid !== undefined && !uid) {
+        warnings.push(`uid ${JSON.stringify(data.uid)} is not a valid UUIDv7 — ignored`);
+    }
+    const issue = {
+        uid,
+        id,
+        title,
+        status: norm.status,
+        severity: str(data.severity),
+        priority: str(data.priority),
+        // An empty tag list and no tag list mean the same thing, and encode omits
+        // empty arrays — so decoding [] to [] would make the codec non-idempotent.
+        // Twelve records in the store carry `tags: []`; the corpus test caught it.
+        tags: normalizeTags(data.tags),
+        // EPIC-0040. Read leniently and warn, matching how this codec treats every
+        // other damaged value: a record whose assignee is malformed is still a
+        // record, and refusing to decode it would hide the rest of its content.
+        // The strict assertion lives at the write boundary.
+        assignee: str(data.assignee),
+        team: str(data.team),
+        epicId: str(data.epic_id) ?? str(data.epicId),
+        // Both spellings exist; `projectId` is the markdown writer's, `project` the
+        // YAML writer's. The model has one, and encode puts it back where it came from.
+        project: str(data.project) ?? str(data.projectId),
+        details: str(data.description) ?? extractDetails(body),
+        resolution: str(data.resolution),
+        created_at: str(data.created_at),
+        updated_at: str(data.updated_at),
+        closed_at: str(data.closed_at),
+    };
+    // Strip model-owned keys; whatever remains is carried through untouched.
+    const preserved = {};
+    for (const [k, v] of Object.entries(data)) {
+        if (!MODEL_KEYS.has(k) && k !== 'projectId')
+            preserved[k] = v;
+    }
+    return { issue, format, raw: { data: preserved, body }, warnings };
+}
+/**
+ * Rewrite the derived header lines in a markdown body from the model.
+ *
+ * Only lines that already exist are updated — this does not inject a mirror
+ * into a record that never had one, because the mirror is a convention of the
+ * markdown writer's layout, not a requirement of the format.
+ */
+function syncBodyMirror(body, issue) {
+    let out = body;
+    out = out.replace(/^\*\*Status:\*\* .*$/m, `**Status:** ${issue.status}`);
+    if (issue.severity) {
+        out = out.replace(/^\*\*Severity:\*\* .*$/m, `**Severity:** ${issue.severity}`);
+    }
+    if (issue.epicId) {
+        out = out.replace(/^\*\*Epic:\*\* .*$/m, `**Epic:** ${issue.epicId}`);
+    }
+    // The heading is the title's home in this format; keep them in step.
+    //
+    // Only ever the FIRST LINE. Splicing a multi-line title into the heading
+    // line pushed its remaining lines into the body as loose prose — and since
+    // the writer had already put them there once, they appeared twice. The
+    // authoritative copy of such a title is in frontmatter (see encodeIssue);
+    // this is the human-readable rendering of it.
+    out = out.replace(/^#\s+.+$/m, `# ${issue.title.split(/\r?\n/)[0]}`);
+    // Resolution is rendered into the body for the same reason status is: a
+    // markdown record is read by people, and `## Resolution` is where they look.
+    // It is regenerated from the model rather than stored there, so it cannot
+    // drift from frontmatter the way the status mirror did. Writing it ONLY to
+    // frontmatter would have been the tidier data model and the worse record —
+    // the prose would have silently vanished from every closed issue.
+    if (issue.resolution) {
+        const section = `## Resolution\n\n${issue.resolution}\n`;
+        out = /^##\s+Resolution\s*$/m.test(out)
+            ? out.replace(/^##\s+Resolution\s*\n[\s\S]*?(?=\n##\s|$)/m, section)
+            : `${out.replace(/\s+$/, '')}\n\n${section}`;
+    }
+    return out;
+}
+export function encodeIssue(decoded) {
+    const { issue, format, raw } = decoded;
+    const data = {};
+    const put = (k, v) => {
+        if (v !== undefined && v !== null && !(Array.isArray(v) && v.length === 0))
+            data[k] = v;
+    };
+    // Field order is stable so diffs stay readable across writes.
+    put('uid', issue.uid);
+    put('id', issue.id);
+    // Markdown records normally carry the title in the `# heading`, and writing
+    // it to frontmatter as well would create a second copy to drift — the same
+    // mistake as the status mirror. But a record with no heading has nowhere else
+    // to keep it, and omitting it there means the title is silently replaced by
+    // the filename on the next read. So: frontmatter holds the title exactly when
+    // the body cannot.
+    //
+    // A MULTI-LINE TITLE IS A TITLE THE BODY CANNOT HOLD. A markdown heading ends
+    // at the newline, so `# first\nsecond` is a heading reading "first" followed
+    // by a stray paragraph, and the record came back a line long with no error
+    // anywhere in the chain (ISS-0155). YAML quotes and escapes it exactly, so
+    // frontmatter is the only container that round-trips one.
+    const bodyHasHeading = /^#\s+.+$/m.test(raw.body);
+    const titleFitsAHeading = !/[\r\n]/.test(issue.title);
+    if (format === 'yaml' || !bodyHasHeading || !titleFitsAHeading)
+        put('title', issue.title);
+    // The markdown writer spells it projectId; keep each format's own spelling so
+    // a rewrite is not a gratuitous diff on every record.
+    put(format === 'md' ? 'projectId' : 'project', issue.project);
+    put('severity', issue.severity);
+    put('status', issue.status);
+    put('priority', issue.priority);
+    put('assignee', issue.assignee);
+    put('team', issue.team);
+    put('epic_id', issue.epicId);
+    put('tags', issue.tags);
+    put('created_at', issue.created_at);
+    put('updated_at', issue.updated_at);
+    put('closed_at', issue.closed_at);
+    // Bare YAML keeps prose in `description`; markdown keeps it in the body.
+    if (format === 'yaml')
+        put('description', issue.details);
+    put('resolution', issue.resolution);
+    // Preserved unknown keys land after the model's, so they never displace a
+    // known field's position but are never lost either.
+    for (const [k, v] of Object.entries(raw.data))
+        if (!(k in data))
+            data[k] = v;
+    const yaml = stringifyYaml(data, { lineWidth: 0 });
+    if (format === 'md') {
+        const body = syncBodyMirror(raw.body, issue);
+        return `---\n${yaml}---\n${body}`;
+    }
+    // A bare-YAML tail should not exist post-Phase-2, but if one is present it is
+    // pre-existing prose and gets preserved rather than dropped.
+    return raw.body.trim() ? `${yaml}\n${raw.body}` : yaml;
+}
+/** Apply changes to a decoded record, keeping derived state consistent. */
+export function applyIssueChanges(decoded, changes) {
+    return { ...decoded, issue: { ...decoded.issue, ...changes } };
+}
+//# sourceMappingURL=issueCodec.js.map

package/dist/domain/issueCodec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issueCodec.js","sourceRoot":"","sources":["../../src/domain/issueCodec.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,kCAAkC;AAClC,+EAA+E;AAC/E,gFAAgF;AAChF,+CAA+C;AAC/C,EAAE;AACF,kCAAkC;AAClC,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,6EAA6E;AAC7E,+EAA+E;AAC/E,6EAA6E;AAC7E,+EAA+E;AAC/E,gEAAgE;AAChE,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,8EAA8E;AAC9E,0EAA0E;AAC1E,gFAAgF;AAChF,4EAA4E;AAC5E,+EAA+E;AAE/E,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,MAAM,CAAC;AACtE,OAAO,EAIL,KAAK,EACL,eAAe,GAChB,MAAM,YAAY,CAAC;AAwBpB,MAAM,cAAc,GAAG,6CAA6C,CAAC;AAErE,8EAA8E;AAC9E,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IACzB,KAAK;IACL,IAAI;IACJ,OAAO;IACP,QAAQ;IACR,UAAU;IACV,UAAU;IACV,UAAU;IACV,MAAM;IACN,MAAM;IACN,SAAS;IACT,QAAQ;IACR,SAAS;IACT,aAAa;IACb,SAAS;IACT,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,WAAW;CACZ,CAAC,CAAC;AAEH,SAAS,aAAa,CAAC,CAAU;IAC/B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpF,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC5C,CAAC;AAED,SAAS,GAAG,CAAC,CAAU;IACrB,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAClE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAChD,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,cAAc,CAAC,IAAY;IAClC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACtD,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IAEzB,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAChB,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,+BAA+B,CAAC,CAAC,CAAC;IACrE,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3C,IAAI,IAAI,EAAE,KAAK,KAAK,SAAS;QAAE,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAEhE,OAAO,IAAI,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,OAAe;IAC3D,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,EAAE,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAExC,IAAI,IAA6B,CAAC;IAClC,IAAI,IAAY,CAAC;IACjB,IAAI,MAAmB,CAAC;IAExB,IAAI,EAAE,EAAE,CAAC;QACP,MAAM,GAAG,IAAI,CAAC;QACd,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;QACb,IAAI,CAAC;YACH,IAAI,GAAI,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,CAA6B,IAAI,EAAE,CAAC;QAC7D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,EAAE,CAAC;YACV,QAAQ,CAAC,IAAI,CAAC,8BAA8B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClG,CAAC;IACH,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,MAAM,CAAC;QAChB,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QAClB,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YACtB,uEAAuE;YACvE,yCAAyC;YACzC,QAAQ,CAAC,IAAI,CAAC,qFAAqF,CAAC,CAAC;QACvG,CAAC;QACD,IAAI,CAAC;YACH,IAAI,GAAI,SAAS,CAAC,KAAK,CAAC,IAAI,CAA6B,IAAI,EAAE,CAAC;QAClE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,EAAE,CAAC;YACV,QAAQ,CAAC,IAAI,CAAC,uBAAuB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3F,CAAC;IACH,CAAC;IAED,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,IAAI,GAAG,EAAE,CAAC;QACV,QAAQ,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;IACrD,CAAC;IAED,4EAA4E;IAC5E,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1B,MAAM,EAAE,GACN,CAAC,IAAI,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QAClE,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE;QACjD,IAAI;QACJ,QAAQ,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;IAEzC,4EAA4E;IAC5E,EAAE;IACF,yEAAyE;IACzE,4EAA4E;IAC5E,6EAA6E;IAC7E,4EAA4E;IAC5E,2EAA2E;IAC3E,qDAAqD;IACrD,EAAE;IACF,6EAA6E;IAC7E,0EAA0E;IAC1E,2CAA2C;IAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IACvD,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,OAAO,IAAI,OAAO,IAAI,QAAQ,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;IAC3E,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;QACzB,QAAQ,CAAC,IAAI,CAAC,gEAAgE,CAAC,CAAC;IAClF,CAAC;IAED,4EAA4E;IAC5E,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;QACtB,QAAQ,CAAC,IAAI,CAAC,uBAAuB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/F,CAAC;SAAM,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;QAC/B,QAAQ,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,cAAc,CAAC,kBAAkB,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9F,CAAC;IAED,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACnD,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,CAAC,GAAG,EAAE,CAAC;QACnC,QAAQ,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;IACnF,CAAC;IAED,MAAM,KAAK,GAAU;QACnB,GAAG;QACH,EAAE;QACF,KAAK;QACL,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAA8B;QACzD,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAA8B;QACzD,0EAA0E;QAC1E,2EAA2E;QAC3E,2EAA2E;QAC3E,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC;QAC9B,2EAA2E;QAC3E,uEAAuE;QACvE,wEAAwE;QACxE,oDAAoD;QACpD,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC;QAC5B,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;QACpB,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC;QAC7C,4EAA4E;QAC5E,gFAAgF;QAChF,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;QACjD,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC;QACtD,UAAU,EAAE,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC;QAChC,UAAU,EAAE,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC;QAChC,UAAU,EAAE,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC;QAChC,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;KAC/B,CAAC;IAEF,yEAAyE;IACzE,MAAM,SAAS,GAA4B,EAAE,CAAC;IAC9C,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,WAAW;YAAE,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAChE,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,CAAC;AACrE,CAAC;AAED;;;;;;GAMG;AACH,SAAS,cAAc,CAAC,IAAY,EAAE,KAAY;IAChD,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,uBAAuB,EAAE,eAAe,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1E,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnB,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,yBAAyB,EAAE,iBAAiB,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjB,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,qBAAqB,EAAE,aAAa,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,qEAAqE;IACrE,EAAE;IACF,yEAAyE;IACzE,2EAA2E;IAC3E,uEAAuE;IACvE,0EAA0E;IAC1E,8CAA8C;IAC9C,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAErE,wEAAwE;IACxE,6EAA6E;IAC7E,0EAA0E;IAC1E,2EAA2E;IAC3E,2EAA2E;IAC3E,kEAAkE;IAClE,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACrB,MAAM,OAAO,GAAG,oBAAoB,KAAK,CAAC,UAAU,IAAI,CAAC;QACzD,GAAG,GAAG,uBAAuB,CAAC,IAAI,CAAC,GAAG,CAAC;YACrC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,4CAA4C,EAAE,OAAO,CAAC;YACpE,CAAC,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,OAAO,EAAE,CAAC;IACjD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAqB;IAC/C,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IAEvC,MAAM,IAAI,GAA4B,EAAE,CAAC;IACzC,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,CAAU,EAAE,EAAE;QACpC,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;YAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC1F,CAAC,CAAC;IAEF,8DAA8D;IAC9D,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IACtB,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;IACpB,4EAA4E;IAC5E,2EAA2E;IAC3E,8EAA8E;IAC9E,4EAA4E;IAC5E,8EAA8E;IAC9E,mBAAmB;IACnB,EAAE;IACF,8EAA8E;IAC9E,6EAA6E;IAC7E,2EAA2E;IAC3E,2EAA2E;IAC3E,0DAA0D;IAC1D,MAAM,cAAc,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClD,MAAM,iBAAiB,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACtD,IAAI,MAAM,KAAK,MAAM,IAAI,CAAC,cAAc,IAAI,CAAC,iBAAiB;QAAE,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1F,8EAA8E;IAC9E,sDAAsD;IACtD,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9D,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAChC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAChC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAChC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IACxB,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IACxB,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IACpC,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IACpC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAClC,yEAAyE;IACzE,IAAI,MAAM,KAAK,MAAM;QAAE,GAAG,CAAC,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACzD,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IAEpC,0EAA0E;IAC1E,oDAAoD;IACpD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;YAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAE7E,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC;IAEnD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC7C,OAAO,QAAQ,IAAI,QAAQ,IAAI,EAAE,CAAC;IACpC,CAAC;IAED,8EAA8E;IAC9E,6DAA6D;IAC7D,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACzD,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,iBAAiB,CAAC,OAAqB,EAAE,OAAuB;IAC9E,OAAO,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,GAAG,OAAO,EAAE,EAAE,CAAC;AACjE,CAAC"}

package/dist/domain/issueRepository.d.ts

@@ -0,0 +1,124 @@
+import { Issue, IssuePriority, IssueSeverity, IssueStatus } from './issue.js';
+import { IssueFormat } from './issueCodec.js';
+/** An issue plus where it lives. The path is for diagnostics, not for callers to write through. */
+/**
+ * What a close actually did. `preservedResolution` is the difference between a
+ * first close and a re-close that kept the original reasoning — without it the
+ * caller cannot tell the two apart, which is how ISS-0168 stayed silent.
+ */
+export interface CloseResult {
+    stored: StoredIssue;
+    preservedResolution: boolean;
+}
+export interface StoredIssue {
+    issue: Issue;
+    filename: string;
+    path: string;
+    format: IssueFormat;
+    /** Integrity observations from decoding. Empty for a healthy record. */
+    warnings: string[];
+}
+export interface IssueListFilter {
+    status?: IssueStatus;
+    /** All non-terminal statuses. Distinct from status:'open', which is one value. */
+    liveOnly?: boolean;
+    epicId?: string;
+}
+export interface CreateIssueSpec {
+    title: string;
+    details: string;
+    severity: IssueSeverity;
+    priority?: IssuePriority;
+    epicId?: string;
+    tags?: string[];
+    project?: string;
+    /** Prefixed identity — user:/agent:/human:. Validated at the tool boundary. */
+    assignee?: string;
+    /** `team:<uuid>`. Validated at the tool boundary. */
+    team?: string;
+}
+/**
+ * Integrity state of the whole store, reported alongside a listing rather than
+ * discovered mid-incident.
+ *
+ * The distinction that matters: `malformed` records are invisible to callers,
+ * so a silent skip would make a broken store look like a shorter clean one.
+ * `degraded` records are readable but carry something the codec had to
+ * interpret. Both are repair queues, not cosmetics — a duplicate id makes an
+ * issue unwritable, because the repository refuses an ambiguous target.
+ */
+export interface StoreIntegrity {
+    malformed: string[];
+    degraded: Array<{
+        filename: string;
+        warnings: string[];
+    }>;
+    duplicateIds: Record<string, string[]>;
+}
+export interface IssueRepository {
+    integrity(): Promise<StoreIntegrity>;
+    list(filter?: IssueListFilter): Promise<StoredIssue[]>;
+    get(idOrFilename: string): Promise<StoredIssue | null>;
+    create(spec: CreateIssueSpec): Promise<StoredIssue>;
+    update(idOrFilename: string, changes: Partial<Issue>): Promise<StoredIssue>;
+    close(idOrFilename: string, resolution: string, status?: 'closed' | 'wontfix'): Promise<CloseResult>;
+}
+export declare class AmbiguousIssueIdError extends Error {
+    readonly issueId: string;
+    readonly candidates: string[];
+    readonly code = "AMBIGUOUS_ISSUE_ID";
+    constructor(issueId: string, candidates: string[]);
+}
+export declare class IssueNotFoundError extends Error {
+    readonly issueId: string;
+    readonly code = "ISSUE_NOT_FOUND";
+    constructor(issueId: string);
+}
+export declare class FsIssueRepository implements IssueRepository {
+    private readonly issuesDir;
+    constructor(issuesDir: string);
+    private readAll;
+    /**
+     * Duplicate detection deliberately runs over EVERY record, never a filtered
+     * subset: a closed twin still makes an id ambiguous for writers, so filtering
+     * it out of a listing must not filter it out of the collision report.
+     */
+    integrity(): Promise<StoreIntegrity>;
+    list(filter?: IssueListFilter): Promise<StoredIssue[]>;
+    /**
+     * Resolve an id to exactly one record, in tiers of decreasing specificity.
+     *
+     * Only the first non-empty tier is considered, and ambiguity is reported
+     * within a tier rather than across tiers — so naming a record by its filename
+     * stays a reliable way to pick one member of a duplicate pair even while the
+     * shared ISS-NNNN remains ambiguous. uid is checked first because it is the
+     * only identifier guaranteed unique by construction.
+     */
+    private resolve;
+    get(idOrFilename: string): Promise<StoredIssue | null>;
+    private requireOne;
+    create(spec: CreateIssueSpec): Promise<StoredIssue>;
+    update(idOrFilename: string, changes: Partial<Issue>): Promise<StoredIssue>;
+    /**
+     * Close a record, or report that it was already closed without touching what
+     * the first close recorded.
+     *
+     * A re-close used to overwrite `resolution` and move `closed_at` forward
+     * (ISS-0168). That is data loss, and silent: the resolution field is the only
+     * place the reasoning behind a fix survives outside a commit message, and the
+     * caller was told "closed" either way. The trigger was operator error — a
+     * `Closes:` trailer naming an already-closed issue — but the failure mode is
+     * not: citing the issue a piece of follow-up work came from is normal, and
+     * every such citation destroyed the original reasoning.
+     *
+     * So a record that is already terminal AND already carries a resolution keeps
+     * both. A status move between closed and wontfix is still honoured, since
+     * that is a real decision; a missing `closed_at` is filled in, since that only
+     * adds. When nothing is left to change the file is not rewritten at all, so a
+     * re-close does not even bump `updated_at`.
+     *
+     * Amending a resolution on purpose is `update`, which says what it does.
+     */
+    close(idOrFilename: string, resolution: string, status?: 'closed' | 'wontfix'): Promise<CloseResult>;
+}
+//# sourceMappingURL=issueRepository.d.ts.map

package/dist/domain/issueRepository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issueRepository.d.ts","sourceRoot":"","sources":["../../src/domain/issueRepository.ts"],"names":[],"mappings":"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"}