@smartmemory/compose 0.1.38-beta → 0.1.40-beta

package/lib/xref-citation.js

@@ -0,0 +1,235 @@
+/**
+ * xref-citation.js — pure parser for inline cross-project external-reference
+ * citations embedded in a ROADMAP/description cell (COMP-MCP-XREF-SCHEMA, #15).
+ *
+ * A citation is an HTML comment so it renders invisibly in markdown:
+ *
+ *   <!-- xref: github owner/repo#123 expect=open -->
+ *   <!-- xref: github smartmemory/compose#7 expect=closed note="shipped X" -->
+ *   <!-- xref: local compose COMP-MCP-VALIDATE expect=COMPLETE -->
+ *   <!-- xref: url https://example.com/spec note="design ref" -->
+ *
+ * Grammar (spec §3.1 EBNF):
+ *   citation   = "<!--" ws "xref:" ws provider ws target
+ *                [ ws "expect=" expect ] [ ws "note=" qstring ] ws "-->"
+ *   provider   = "github" | "local" | "url"                       ; resolvable
+ *              | "jira" | "linear" | "notion" | "obsidian"         ; reserved url-class
+ *   gh_target  = repo "#" issue          ; repo = owner "/" name
+ *   local_target = repo_token ws feature_code
+ *   url_target = URL                     ; url + every reserved provider
+ *
+ * This module performs ZERO I/O and ZERO network. It is a pure
+ * string → object function. Consumed by #16 (`runExternalRefChecks`); #15
+ * ships it standalone with no caller in the validator path.
+ */
+
+// url-class = `url` + every reserved provider (carry a url_target, never
+// resolved in v1). ALL_PROVIDERS is the full accepted set.
+const RESOLVABLE_PROVIDERS = ['github', 'local', 'url'];
+const RESERVED_PROVIDERS = ['jira', 'linear', 'notion', 'obsidian'];
+const ALL_PROVIDERS = new Set([...RESOLVABLE_PROVIDERS, ...RESERVED_PROVIDERS]);
+
+const GITHUB_EXPECT = new Set(['open', 'closed']);
+const LOCAL_EXPECT = new Set([
+  'PLANNED', 'IN_PROGRESS', 'PARTIAL', 'COMPLETE',
+  'SUPERSEDED', 'PARKED', 'BLOCKED', 'KILLED',
+]);
+const FEATURE_CODE_RE = /^[A-Z][A-Z0-9-]*[A-Z0-9]$/;
+const URI_SCHEME_RE = /^[a-zA-Z][a-zA-Z0-9+\-.]*:\/\//;
+
+// Anchored scan: only HTML comments whose body begins with `xref:` are
+// considered. Any other `<!-- ... -->` is ignored entirely.
+const CITATION_RE = /<!--\s*xref:\s*([\s\S]*?)\s*-->/g;
+
+/**
+ * Structured parse error for a comment that matched `<!--\s*xref:` but
+ * failed the grammar. Consumed by #16 as the `XREF_MALFORMED` finding;
+ * #15 only surfaces it via the return value (never throws, never logs).
+ */
+export class ParseError {
+  constructor(raw, reason) {
+    this.raw = raw;
+    this.reason = reason;
+  }
+}
+
+/**
+ * @typedef {object} PartialExternalRef
+ * @property {string} provider
+ * @property {string|null} repo     github "owner/name" | local repo token | null
+ * @property {number|null} issue    github only
+ * @property {string|null} toCode   local only (target feature code)
+ * @property {string|null} url      url-class only (url + reserved providers)
+ * @property {string|null} expect   optional expected-state token
+ * @property {string|null} note
+ * @property {string} raw           the citation body (for locatability)
+ */
+
+/**
+ * Parse every `xref:` citation in a description cell.
+ * @param {string} descriptionCell
+ * @returns {{ refs: PartialExternalRef[], errors: ParseError[] }}
+ */
+export function parseCitations(descriptionCell) {
+  const refs = [];
+  const errors = [];
+  if (typeof descriptionCell !== 'string' || descriptionCell.length === 0) {
+    return { refs, errors };
+  }
+
+  CITATION_RE.lastIndex = 0;
+  let m;
+  while ((m = CITATION_RE.exec(descriptionCell)) !== null) {
+    const raw = m[1];
+    try {
+      refs.push(parseOne(raw));
+    } catch (e) {
+      if (e instanceof ParseError) errors.push(e);
+      else errors.push(new ParseError(raw, String(e && e.message ? e.message : e)));
+    }
+  }
+  return { refs, errors };
+}
+
+function parseOne(raw) {
+  let rest = raw.trim();
+  if (rest.length === 0) throw new ParseError(raw, 'empty xref citation');
+
+  // Optional trailing options `expect=<tok>` and `note="..."`, order-
+  // independent. They are stripped **end-anchored** (must be the trailing
+  // whitespace-separated token), so a `note=`/`expect=` substring inside the
+  // target itself — e.g. a URL query `https://x/?note=a&expect=b` — is left
+  // in the target and never mis-consumed. Each option may appear at most once.
+  //
+  // Known v1 limitations (faithful to spec §3.1 EBNF, which defines
+  // `qstring = DQUOTE *CHAR DQUOTE` with no escape and an HTML-comment
+  // carrier): a `note="..."` value cannot contain `"` or the literal `-->`.
+  let note = null;
+  let expect = null;
+  for (let i = 0; i < 2; i++) {
+    let m;
+    if (note === null && (m = rest.match(/\s+note="([^"]*)"\s*$/))) {
+      note = m[1];
+      rest = rest.slice(0, m.index).trimEnd();
+      continue;
+    }
+    if (expect === null && (m = rest.match(/\s+expect=(\S+)\s*$/))) {
+      expect = m[1];
+      rest = rest.slice(0, m.index).trimEnd();
+      continue;
+    }
+    break;
+  }
+  // A `note=` option token that exists but was not consumable as a trailing
+  // quoted string is a hard parse error (don't silently fold it into target).
+  if (note === null && /(^|\s)note=/.test(rest)) {
+    if (/(^|\s)note="/.test(rest)) {
+      throw new ParseError(raw, 'unterminated or misplaced note="..." (must be a trailing double-quoted token)');
+    }
+    throw new ParseError(raw, 'note= value must be a double-quoted string');
+  }
+  // Likewise a stray trailing `expect=` token that wasn't consumed.
+  if (expect === null && /(^|\s)expect=\S*\s*$/.test(rest)) {
+    throw new ParseError(raw, 'malformed expect= option');
+  }
+  rest = rest.replace(/\s+/g, ' ').trim();
+
+  // Remaining: `<provider> <target...>`.
+  const firstWs = rest.search(/\s/);
+  if (firstWs === -1) {
+    throw new ParseError(raw, `missing target after provider "${rest}"`);
+  }
+  const provider = rest.slice(0, firstWs);
+  const target = rest.slice(firstWs + 1).trim();
+
+  if (!ALL_PROVIDERS.has(provider)) {
+    throw new ParseError(
+      raw,
+      `unknown provider "${provider}" (expected one of ${[...ALL_PROVIDERS].join(', ')})`,
+    );
+  }
+  if (target.length === 0) {
+    throw new ParseError(raw, `missing target for provider "${provider}"`);
+  }
+
+  const ref = {
+    provider,
+    repo: null,
+    issue: null,
+    toCode: null,
+    url: null,
+    expect: null,
+    note,
+    raw,
+  };
+
+  if (provider === 'github') {
+    // No `#` in either repo half — `#` delimits the issue (owner/name#issue)
+    // and GitHub owners/names cannot contain it. Keeps the citation carrier
+    // carrier-equivalent with the feature.json-link writer (XREF_GH_REPO_RE).
+    const gh = target.match(/^([^\s/#]+\/[^\s/#]+)#(\d+)$/);
+    if (!gh) {
+      throw new ParseError(raw, `github target must be "owner/name#issue", got "${target}"`);
+    }
+    ref.repo = gh[1];
+    ref.issue = Number(gh[2]);
+    if (expect !== null) {
+      if (!GITHUB_EXPECT.has(expect)) {
+        throw new ParseError(
+          raw, `github expect must be open|closed, got "${expect}"`,
+        );
+      }
+      ref.expect = expect;
+    }
+  } else if (provider === 'local') {
+    const parts = target.split(/\s+/);
+    if (parts.length !== 2) {
+      throw new ParseError(
+        raw, `local target must be "<repo> <FEATURE_CODE>", got "${target}"`,
+      );
+    }
+    const [repoTok, code] = parts;
+    // repo token must be a single safe directory name — it is resolved as a
+    // sibling dir (path.join(cwd, '..', repoTok)); reject anything with a
+    // path separator or traversal so a citation cannot escape the workspace.
+    if (!/^[A-Za-z0-9._-]+$/.test(repoTok) || repoTok === '.' || repoTok === '..') {
+      throw new ParseError(
+        raw,
+        `local repo token "${repoTok}" must be a single directory name `
+        + '([A-Za-z0-9._-], no path separators or "."/"..")',
+      );
+    }
+    if (!FEATURE_CODE_RE.test(code)) {
+      throw new ParseError(raw, `local target feature code "${code}" is not a valid code`);
+    }
+    ref.repo = repoTok;
+    ref.toCode = code;
+    if (expect !== null) {
+      if (!LOCAL_EXPECT.has(expect)) {
+        throw new ParseError(
+          raw,
+          `local expect must be one of ${[...LOCAL_EXPECT].join('|')}, got "${expect}"`,
+        );
+      }
+      ref.expect = expect;
+    }
+  } else {
+    // url-class: provider `url` and every reserved provider. The target is a
+    // single URL token; `expect=` is syntactically accepted but ignored
+    // (these refs are never resolved in v1 — spec §5.2/§9), never a ParseError.
+    if (/\s/.test(target)) {
+      throw new ParseError(
+        raw, `${provider} target must be a single URL, got "${target}"`,
+      );
+    }
+    if (!URI_SCHEME_RE.test(target)) {
+      throw new ParseError(
+        raw, `${provider} target must be a scheme:// URL, got "${target}"`,
+      );
+    }
+    ref.url = target;
+    if (expect !== null) ref.expect = expect; // recorded, not validated, not resolved
+  }
+
+  return ref;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.1.38-beta",
+  "version": "0.1.40-beta",
   "description": "Structured AI dev pipeline — goal-to-product orchestration with gates, iteration loops, and feature lifecycle management.",
   "author": "SmartMemory",
   "license": "MIT",

package/server/compose-mcp-tools.js

@@ -291,10 +291,11 @@ export async function toolValidateFeature(args = {}) {
 
 export async function toolValidateProject(args = {}) {
   const { validateProject } = await import('../lib/feature-validator.js');
-  const { external_prefixes, feature_json_mode } = args;
+  const { external_prefixes, feature_json_mode, external } = args;
   return validateProject(getTargetRoot(), {
     externalPrefixes: external_prefixes,
     featureJsonMode: feature_json_mode,
+    external: external === true,
   });
 }
 

package/server/compose-mcp.js

@@ -363,12 +363,13 @@ const TOOLS = [
   },
   {
     name: 'validate_project',
-    description: 'Run validate_feature for every code in vision-state, ROADMAP, and folders, plus cross-cutting checks (orphan folders, dangling cross-refs, CHANGELOG references, journal index drift). Returns the union of all findings.',
+    description: 'Run validate_feature for every code in vision-state, ROADMAP, and folders, plus cross-cutting checks (orphan folders, dangling cross-refs, CHANGELOG references, journal index drift) and read-only external-reference staleness (kind:"external" links + xref: roadmap citations). external:true enables network resolution of github refs (off by default — github refs then emit XREF_RESOLUTION_SKIPPED). Returns the union of all findings.',
     inputSchema: {
       type: 'object',
       properties: {
         external_prefixes: { type: 'array', items: { type: 'string' } },
         feature_json_mode: { type: 'boolean' },
+        external: { type: 'boolean', description: 'Resolve github external refs over the network (read-only). Default false: github refs degrade to XREF_RESOLUTION_SKIPPED.' },
       },
     },
   },
@@ -411,14 +412,19 @@ const TOOLS = [
   },
   {
     name: 'link_features',
-    description: 'Register a typed cross-feature relationship. Stores on the source feature; query the inverse via get_feature_links(direction:"incoming"). Closed enum on kind; self-links rejected; dedups on (kind, to_code).',
+    description: 'Register a typed cross-feature relationship. Two shapes: (1) SAME-PROJECT — kind ∈ surfaced_by|blocks|depends_on|follow_up|supersedes|related, requires to_code; self-links rejected; dedups on (kind,to_code). (2) EXTERNAL (kind:"external") — a cross-project pointer, NOT a same-project link: requires provider; three resolvable sub-shapes — github (repo "owner/name" + integer issue), local (repo token + to_code), url (url); plus reserved url-class providers jira|linear|notion|obsidian (parse-valid, require url, NOT resolved in v1). External dedups on (kind=external, provider, repo, issue|to_code|url). Stores on the source feature; query inverse via get_feature_links(direction:"incoming").',
     inputSchema: {
       type: 'object',
-      required: ['from_code', 'to_code', 'kind'],
+      required: ['from_code', 'kind'],
       properties: {
         from_code: { type: 'string' },
-        to_code: { type: 'string', description: 'Target feature code. Need not exist yet (you can link to a code you are about to create).' },
-        kind: { type: 'string', enum: ['surfaced_by', 'blocks', 'depends_on', 'follow_up', 'supersedes', 'related'] },
+        to_code: { type: 'string', description: 'Same-project: target feature code (required unless kind:"external"). External local: the cited feature code. Need not exist yet.' },
+        kind: { type: 'string', enum: ['surfaced_by', 'blocks', 'depends_on', 'follow_up', 'supersedes', 'related', 'external'] },
+        provider: { type: 'string', enum: ['github', 'local', 'url', 'jira', 'linear', 'notion', 'obsidian'], description: 'Required when kind:"external". Resolvable: github|local|url. Reserved url-class (require url, not resolved in v1): jira|linear|notion|obsidian.' },
+        repo: { type: 'string', description: 'External github: "owner/name". External local: workspace-relative repo token.' },
+        issue: { type: 'integer', minimum: 1, description: 'External github: issue/PR number.' },
+        url: { type: 'string', description: 'External url-class (url|jira|linear|notion|obsidian): the pointer URL.' },
+        expect: { type: 'string', description: 'Optional expected state. github: open|closed. local: a status token. url-class: recorded, never resolved.' },
         note: { type: 'string' },
         force: { type: 'boolean' },
         idempotency_key: { type: 'string' },

package/dist/assets/channel-GvJclmQg.js

@@ -1 +0,0 @@
-import{U as a,C as n}from"./App-BOmZUQK9.js";const t=(r,o)=>a.lang.round(n.parse(r)[o]);export{t as c};

package/dist/assets/classDiagram-4FO5ZUOK-DV6SPGMl.js

@@ -1 +0,0 @@
-import{s as a,a as s,c as e,C as t}from"./chunk-727SXJPM-rxaajQx0.js";import{b as i}from"./App-BOmZUQK9.js";import"./chunk-FMBD7UC4-FSbyjfSh.js";import"./chunk-ND2GUHAM-DhD_mt3D.js";import"./chunk-55IACEB6-C074eKNZ.js";import"./chunk-2J33WTMH-DsfEX96t.js";import"./mobile-BwduHUEq.js";import"./index-DHyg44Px.js";import"./graph-uO5hwVZK.js";var f={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{f as diagram};

package/dist/assets/classDiagram-v2-Q7XG4LA2-DV6SPGMl.js

@@ -1 +0,0 @@
-import{s as a,a as s,c as e,C as t}from"./chunk-727SXJPM-rxaajQx0.js";import{b as i}from"./App-BOmZUQK9.js";import"./chunk-FMBD7UC4-FSbyjfSh.js";import"./chunk-ND2GUHAM-DhD_mt3D.js";import"./chunk-55IACEB6-C074eKNZ.js";import"./chunk-2J33WTMH-DsfEX96t.js";import"./mobile-BwduHUEq.js";import"./index-DHyg44Px.js";import"./graph-uO5hwVZK.js";var f={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{f as diagram};

package/dist/assets/stateDiagram-v2-BHNVJYJU-BK-1uf4O.js

@@ -1 +0,0 @@
-import{b as r,a as e,s as a,S as s}from"./chunk-AQP2D5EJ-Cg6-5M28.js";import{b as i}from"./App-BOmZUQK9.js";import"./chunk-55IACEB6-C074eKNZ.js";import"./chunk-2J33WTMH-DsfEX96t.js";import"./mobile-BwduHUEq.js";import"./index-DHyg44Px.js";import"./graph-uO5hwVZK.js";var b={parser:a,get db(){return new s(2)},renderer:e,styles:r,init:i(t=>{t.state||(t.state={}),t.state.arrowMarkerAbsolute=t.arrowMarkerAbsolute},"init")};export{b as diagram};