spexcode 0.6.2 → 0.6.6

package/node_modules/@spexcode/spec-cli/dist/issues.d.ts

@@ -0,0 +1,69 @@
+import type { ForgeIssue, ForgeLabel, ForgePR } from '@spexcode/spec-forge/port';
+import { type DispatchOutcome } from './mentions.js';
+import type { Reply, Issue, RemarkTrack } from '@spexcode/spec-eval/remarks';
+export type { Reply, Issue } from '@spexcode/spec-eval/remarks';
+export declare const isRemark: (r: Reply) => boolean;
+export type IssueLabel = ForgeLabel;
+export type ForgeState = {
+    issues: ForgeIssue[];
+    prs: ForgePR[];
+};
+export type ForgeSlice = {
+    host: string;
+    state: ForgeState;
+};
+export type IssueStore = {
+    id: string;
+    label: string;
+    kind: 'local' | 'forge';
+    writable: true;
+};
+export declare function issueStores(): IssueStore[];
+export declare const trackKey: (node: string, scenario: string) => string;
+export declare const isEvalConcern: (concern: string) => boolean;
+export declare function loadEvalRemarkTracks(): Map<string, RemarkTrack>;
+export declare function fromForge(slice: ForgeSlice, nodeIds: string[]): Issue[];
+export declare function mergedIssues(forge: ForgeSlice | null, nodeIds: string[]): Issue[];
+export declare function boardThreads(forge: ForgeSlice | null, nodeIds: string[]): {
+    issues: Issue[];
+    stamp: string;
+};
+export declare function threadStamp(threads: Issue[]): string;
+export declare function createIssue(concern: string, opts?: {
+    store?: string;
+    nodes?: string[];
+    body?: string;
+    evidence?: string[];
+    author?: string;
+}): Promise<{
+    store: string;
+    id: string;
+    nodes: string[];
+    url?: string;
+    outcomes: DispatchOutcome[];
+}>;
+export declare function promote(id: string, opts?: {
+    author?: string;
+}): Promise<{
+    url: string;
+    number: number;
+    host: string;
+}>;
+export declare function replyIssue(id: string, body: string, opts?: {
+    author?: string;
+    node?: string | null;
+    evidence?: string[];
+}): Promise<{
+    store: string;
+    replies?: Reply[];
+    url?: string;
+    thread?: Issue;
+    author: string;
+    outcomes: DispatchOutcome[];
+}>;
+export declare function closeIssue(id: string): Promise<{
+    store: string;
+    status: string;
+    url?: string;
+}>;
+export declare function findIssue(id: string, forge: ForgeSlice | null, nodeIds: string[]): Issue | undefined;

package/node_modules/@spexcode/spec-cli/dist/issues.js

@@ -0,0 +1,189 @@
+import { resolveLinks } from '@spexcode/spec-forge/links';
+import { FORGE_DRIVERS, forgeDriverFor, forgeIssueStores, resolveForgeHost } from '@spexcode/spec-forge/drivers';
+import { closeLocalIssue, loadLocalIssues, loadOne, postLocalIssue, reply, replyLocalIssue, parseEvalConcern } from './localIssues.js';
+import { dispatchNewMentions, parseMentions } from './mentions.js';
+import { envSessionId } from '@spexcode/spec-core';
+// A Reply is a plain thread post `{by, at, body}` — OR, when it carries the fields below, a REMARK
+// ([[remark-substrate]]): a reply that pins a RESOLVABLE concern to its host (an issue or a scenario). A
+// remark is not a new record type: it is a reply with the mutable `resolved` bit, a stable `rid` (so it is
+// addressable across retracts), and the `targetCodeSha` it was authored against (the reading it judges). A
+// plain reply omits them all and parses/serializes unchanged (backward compatible). `isRemark` = rid set.
+export const isRemark = (r) => r.rid !== undefined;
+export function issueStores() {
+    return [
+        { id: 'local', label: 'local', kind: 'local', writable: true },
+        ...forgeIssueStores().map((s) => ({ ...s, writable: true })),
+    ];
+}
+function inferNodes(concern, body, explicit = []) {
+    return [...new Set([...explicit, ...parseMentions(`${concern}\n${body || ''}`).nodes])];
+}
+function forgeIssueBody(concern, body, nodes, evidence = []) {
+    return [
+        (body || `(no detail given — ${concern})`).trim(),
+        nodes.length ? `Spec: ${nodes.join(', ')}` : '',
+        evidence.length ? `Evidence: ${evidence.join(', ')} (evidence content hashes)` : '',
+    ].filter(Boolean).join('\n\n');
+}
+// ── the (node, scenario) ↔ eval-thread join ([[remark-teeth]]) ────────────────────────────────────────
+// A scenario's remark track lives ONCE in trunk, keyed by its `eval: <node> · <scenario>` concern thread
+// (R4). This is the ONE server-side overlay: the same join the dashboard's Annotator used to compute
+// client-side (concern-key matching), lifted here so the CLI, the board fold, the session proof, and the
+// annotator all read ONE join. It returns, per pair, the thread plus its REMARK replies (the resolvable
+// ones — a plain comment on the thread is not a remark). The teeth ([[remark-teeth]]) read the remark
+// signals; the annotator reads the thread.
+// `eval: <node> · <scenario>` — node first (never contains ' · '), then the scenario (may). One thread per
+// pair (EventDetail.jsx evalConcern / localIssues.ts resolveRemarkHost mint it), so the last write wins is fine.
+export const trackKey = (node, scenario) => `${node} · ${scenario}`;
+// an eval-remark thread is the eval scoreboard's data, NOT a drain-worthy issue (I1: a scenario-scoped
+// concern is a remark, never an issue). Its `eval: <node> · <scenario>` concern is the tell — the SAME key
+// loadEvalRemarkTracks isolates them by. The two reads are complementary over one store: mergedIssues (the
+// ISSUE surfaces) excludes these; loadEvalRemarkTracks (the EVAL surfaces) keeps only these.
+export const isEvalConcern = (concern) => !!parseEvalConcern(concern);
+// read the whole local store ONCE and split the eval-concern threads out (directive 3): trunk-scoped,
+// read-time, no branch write. A remark whose scenario no longer exists still LOADS here (it just keys a pair
+// no reading joins) — never a crash, per [[remark-teeth]]'s dangling clause.
+export function loadEvalRemarkTracks() {
+    const out = new Map();
+    for (const t of loadLocalIssues()) {
+        const parsed = parseEvalConcern(t.concern);
+        if (!parsed)
+            continue;
+        const { node, scenario } = parsed;
+        out.set(trackKey(node, scenario), { threadId: t.id, node, scenario, thread: t, remarks: t.replies.filter(isRemark) });
+    }
+    return out;
+}
+// forge → Issue, at the adapter boundary: the host's node-naming conventions (`Spec:` body marker +
+// transitive PR links — spec-forge links.ts) become plain `nodes[]` HERE, validated against the real node
+// ids, so nothing downstream ever knows a marker existed. Every raw issue maps — linked or not — because
+// the merged list is the whole set, not just the per-node view.
+export function fromForge(slice, nodeIds) {
+    const nodesByNumber = new Map();
+    for (const link of resolveLinks(slice.state.issues, slice.state.prs, nodeIds))
+        for (const i of link.issues) {
+            const arr = nodesByNumber.get(i.number) ?? [];
+            arr.push(link.node);
+            nodesByNumber.set(i.number, arr);
+        }
+    return slice.state.issues.map((i) => ({
+        id: `${slice.host}#${i.number}`,
+        store: slice.host,
+        concern: i.title,
+        by: i.author,
+        status: (i.state || '').toLowerCase(),
+        nodes: nodesByNumber.get(i.number) ?? [],
+        created: i.createdAt,
+        body: i.body,
+        // the forge comments ARE the thread — the same Reply shape a local thread carries, so nothing
+        // downstream renders two kinds of discussion.
+        replies: (i.comments ?? []).map((c) => ({ by: c.author, at: c.createdAt, body: c.body })),
+        evidence: [],
+        labels: i.labels,
+        url: i.url,
+    }));
+}
+// the one merged read: local issue-store threads + the caller-supplied forge slice, ONE time line — the
+// stores are the same abstraction, so they interleave by creation time, newest first (never
+// store-grouped; a reader's eye lands on what just happened, whatever store holds it). CALLERS own
+// freshness — the server passes the resident cache's state (instant, background reconcile), the CLI a
+// live pull — so the merge itself stays pure. Eval-remark threads are SPLIT OUT read-time (isEvalConcern):
+// they are the eval scoreboard's data, not issues, so every issue surface this feeds — the Threads tab, the
+// board issue badge, the `spex issue ls` drain — is free of them by construction (they reach the EVAL side
+// through loadEvalRemarkTracks / the reading overlay instead).
+export function mergedIssues(forge, nodeIds) {
+    return allThreads(forge, nodeIds).filter((i) => !isEvalConcern(i.concern));
+}
+// the same one merged read BEFORE the read-time split: every thread in the store, both halves, one walk.
+// Deliberately NOT exported — the split above is what every SURFACE read owes ([[eval-issue-split]]), and
+// an unsplit set escaping to a surface would put eval remarks back in the issue drain. The one consumer
+// whose question is about the STORE ITSELF reaches it through boardThreads below.
+function allThreads(forge, nodeIds) {
+    const remote = forge ? fromForge(forge, nodeIds) : [];
+    return [...loadLocalIssues(), ...remote].sort((a, b) => b.created.localeCompare(a.created));
+}
+export function boardThreads(forge, nodeIds) {
+    const threads = allThreads(forge, nodeIds);
+    return { issues: threads.filter((i) => !isEvalConcern(i.concern)), stamp: threadStamp(threads) };
+}
+export function threadStamp(threads) {
+    return [
+        threads.filter((i) => i.status === 'open').length,
+        threads.length,
+        threads.reduce((n, i) => n + i.replies.length, 0),
+        threads.flatMap((i) => [i.created, ...i.replies.flatMap((r) => [r.at, r.resolvedAt ?? ''])]).reduce((a, b) => (b > a ? b : a), ''),
+    ].join(':');
+}
+export async function createIssue(concern, opts = {}) {
+    const store = opts.store || 'local';
+    const author = opts.author || envSessionId() || 'unknown';
+    if (store === 'local') {
+        const { thread, outcomes } = await postLocalIssue(concern, {
+            nodes: opts.nodes,
+            body: opts.body,
+            evidence: opts.evidence,
+            author,
+        });
+        return { store: 'local', id: thread.id, nodes: thread.nodes, outcomes };
+    }
+    const driver = forgeDriverFor(store);
+    if (!driver)
+        throw new Error(`unknown issue store '${store}' (known: ${issueStores().map((s) => s.id).join(', ')})`);
+    const nodes = inferNodes(concern, opts.body, opts.nodes);
+    const { number, url } = await driver.createIssue({
+        title: concern,
+        body: forgeIssueBody(concern, opts.body, nodes, opts.evidence),
+    });
+    const id = `${driver.host}#${number}`;
+    return { store: driver.host, id, nodes, url, outcomes: await dispatchNewMentions(opts.body || concern, { threadId: id, node: nodes[0] || null, author, status: 'open' }) };
+}
+export async function promote(id, opts = {}) {
+    const author = opts.author || envSessionId() || 'unknown';
+    const t = loadOne(id);
+    if (t.status !== 'open')
+        throw new Error(`'${id}' is ${t.status} — only an open local issue promotes`);
+    const host = resolveForgeHost();
+    const driver = forgeDriverFor(host);
+    if (!driver)
+        throw new Error(`no driver for this repo's forge host '${host}' (known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')}) — promotion needs one`);
+    const body = [
+        t.body,
+        t.nodes.length ? `\nSpec: ${t.nodes.join(', ')}` : '',
+        t.evidence.length ? `\nEvidence: ${t.evidence.join(', ')} (evidence content hashes)` : '',
+        `\n---\nPromoted from the local issue \`${id}\` (opened by ${t.by} @ ${t.created}; promoted by ${author}).`,
+    ].filter(Boolean).join('\n');
+    const { number, url } = await driver.createIssue({ title: t.concern, body });
+    reply(id, `promoted to the forge: ${url}`, author);
+    closeLocalIssue(id);
+    return { url, number, host: driver.host };
+}
+export async function replyIssue(id, body, opts = {}) {
+    const author = opts.author || envSessionId() || 'unknown';
+    const forge = /^([A-Za-z0-9-]+)#(\d+)$/.exec(id);
+    if (!forge) {
+        // evidence hashes accrue onto the local thread's typed evidence[] (a forge thread has no such field —
+        // an annotation's frame rides its comment body's image link there, the driver the only network toucher);
+        const { thread, outcomes } = await replyLocalIssue(id, body, author, opts.evidence);
+        // the thread rides along so [[loop-in]] can resolve this reply's originator chain without a second read.
+        return { store: 'local', replies: thread.replies, thread, author, outcomes };
+    }
+    const driver = forgeDriverFor(forge[1]);
+    if (!driver)
+        throw new Error(`unknown forge host '${forge[1]}' — known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')}`);
+    const { url } = await driver.createComment({ number: parseInt(forge[2], 10), body });
+    return { store: forge[1], url, author, outcomes: await dispatchNewMentions(body, { threadId: id, node: opts.node ?? null, author }) };
+}
+export async function closeIssue(id) {
+    const forge = /^([A-Za-z0-9-]+)#(\d+)$/.exec(id);
+    if (!forge)
+        return { store: 'local', status: closeLocalIssue(id).status };
+    const driver = forgeDriverFor(forge[1]);
+    if (!driver)
+        throw new Error(`unknown forge host '${forge[1]}' — known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')}`);
+    const { url } = await driver.closeIssue({ number: parseInt(forge[2], 10) });
+    return { store: forge[1], status: 'closed', url };
+}
+// ───────────────────────── CLI ─────────────────────────
+export function findIssue(id, forge, nodeIds) {
+    return mergedIssues(id.includes('#') ? forge : null, nodeIds).find((i) => i.id === id);
+}

package/node_modules/@spexcode/spec-cli/dist/lint.d.ts

@@ -0,0 +1,34 @@
+export type Finding = {
+    level: 'error' | 'warn';
+    rule: string;
+    spec?: string;
+    file?: string;
+    msg: string;
+};
+export declare const SPEC_LINT_REPORT_PROJECTION = "spex.spec-lint.report";
+export declare const SPEC_LINT_REPORT_SCHEMA_VERSION = 1;
+export type SpecLintReport = {
+    projection: typeof SPEC_LINT_REPORT_PROJECTION;
+    schemaVersion: typeof SPEC_LINT_REPORT_SCHEMA_VERSION;
+    sourceFiles: string[];
+    findings: Finding[];
+};
+export type LintConfig = {
+    governedRoots: string[];
+    sourceIncludeGlobs: string[] | null;
+    sourceExcludeGlobs: string[];
+    sourceExtensions: string[] | null;
+    testGlobs: string[];
+    maxOwners: number;
+    scenarioTags: string[];
+    scopedCodeMiss: 'warn' | 'ignore';
+};
+export declare function loadConfig(root: string, pendingSource?: string | null): LintConfig;
+export declare function normalizeConfig(cfg: LintConfig): LintConfig;
+export type SpecLintOptions = {
+    tip?: string;
+};
+export declare function pendingTouchesGoverned(root: string, tip: string): Promise<boolean>;
+export declare function specLint(root?: string, regs?: import("@spexcode/spec-core").Extractor[], options?: SpecLintOptions): Promise<Finding[]>;
+export declare function specLintReport(root?: string, regs?: import("@spexcode/spec-core").Extractor[], options?: SpecLintOptions): Promise<SpecLintReport>;
+export declare const DRIFT_GUIDANCE = "DRIFT \u2014 a governed file has moved ahead of its spec. A CHECKPOINT, not a chore: find WHERE the truth\nbroke along  raw intent \u2192 expanded spec \u2192 code: link \u2192 code structure \u2192 implementation, fix THAT layer.\n\n  Inspect:  spex spec lint                                                       which files, against which spec\n            the node's spec.md                                             its raw source + expanded spec\n            git diff $(git log -1 --format=%H -- <spec.md>)..HEAD -- <file>   the code delta since the spec\n\nDiagnose, then apply the one honest remedy:\n  \u2022 contract changed        \u2192 rewrite the spec body to the new intent, commit it (re-versions the node)\n  \u2022 only mechanics changed  \u2192 spex spec ack <node>   \"checked \u2014 spec still valid\"   (give a real reason)\n  \u2022 implementation is WRONG \u2192 the spec is right; fix the CODE back toward it, then ack\n  \u2022 wrong code: link        \u2192 the node shouldn't own this file (or owns it too broadly); fix frontmatter\n  \u2022 expanded spec \u2260 raw     \u2192 the spec drifted from human intent; fix the expanded spec to serve the raw\n  \u2022 structural mismatch     \u2192 one file owned by many specs / a feature with no home: refactor so a file\n                              maps to a node, or file an issue and link it (defer honestly)\n\nNever patch. A reasoned ack or a real fix are recorded and re-judged at review; a blind ack is a lie.";