npm - cans-spec - Versions diffs - 0.1.0 - Mend

cans-spec 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (34) hide show

package/LICENSE +21 -0
package/README.md +339 -0
package/package.json +38 -0
package/src/cli.ts +48 -0
package/src/commands/budget.ts +238 -0
package/src/commands/check.ts +422 -0
package/src/commands/done.ts +171 -0
package/src/commands/export.ts +223 -0
package/src/commands/import.ts +436 -0
package/src/commands/init.ts +184 -0
package/src/commands/new.ts +138 -0
package/src/commands/status.ts +152 -0
package/src/converters/index.ts +4 -0
package/src/converters/logseq.ts +42 -0
package/src/converters/obsidian.ts +95 -0
package/src/converters/opml.ts +143 -0
package/src/converters/shared.ts +268 -0
package/src/core/args.ts +79 -0
package/src/core/fs.ts +309 -0
package/src/core/index.ts +10 -0
package/src/core/outline.ts +237 -0
package/src/core/output.ts +300 -0
package/src/core/overflow.ts +75 -0
package/src/core/redundancy.ts +261 -0
package/src/core/refs.ts +275 -0
package/src/core/rules.ts +483 -0
package/src/core/structure.ts +86 -0
package/src/core/style.ts +75 -0
package/src/core/token-budget.ts +284 -0
package/src/types.ts +284 -0
package/templates/AGENTS.md +209 -0
package/templates/_rules.yaml +46 -0
package/templates/adr-template.md +28 -0
package/templates/task-template.md +15 -0

package/src/converters/opml.ts ADDED Viewed

@@ -0,0 +1,143 @@
+import type { ExternalNode } from '../types';
+/** Escape the five XML entities. `&` first so output is never double-encoded. */
+export function encodeXmlEntity(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+/** Inverse of encodeXmlEntity. `&amp;` last so `&amp;lt;` decodes to literal `&lt;`. */
+export function decodeXmlEntity(s: string): string {
+  return s
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#(\d+);/g, (_m, d: string) => String.fromCharCode(Number(d)))
+    .replace(/&amp;/g, '&');
+}
+/** §28 import inverse (OPML/Dynalist): export encodes CANS `see: X.md#Y` as the
+ *  text `→ X.md#Y`; import must restore the ref or the round-trip kills it
+ *  (QA-05 F16 / QA-09 D9). Prose arrows are untouched — the target must be an
+ *  `.md` path (`Draft → Tested` stays prose). */
+export function convertArrowRefs(text: string): string {
+  return text.replace(
+    /→\s*([A-Za-z0-9._/-]+\.md)(#([^\s]+))?/g,
+    (_m, file: string, _anchorPart: string | undefined, anchor: string | undefined) =>
+      anchor !== undefined ? `see: ${file}#${anchor}` : `see: ${file}`,
+  );
+}
+/** Extract the `<head><title>` text (XML-decoded). `cans export` writes the
+ *  SOURCE SPEC FILENAME there (e.g. `02-authentication.md`), so import can
+ *  match the merge target and preserve file identity instead of renumbering
+ *  from the first node (QA-09 D12). null when the document has no title. */
+export function parseOpmlTitle(source: string): string | null {
+  const m = source.match(/<title[^>]*>([\s\S]*?)<\/title\s*>/i);
+  return m ? decodeXmlEntity(m[1]).trim() : null;
+}
+function readAttr(attrs: string, name: string): string | undefined {
+  const m =
+    attrs.match(new RegExp(`(?:^|\\s)${name}\\s*=\\s*"([^"]*)"`, 'i')) ??
+    attrs.match(new RegExp(`(?:^|\\s)${name}\\s*=\\s*'([^']*)'`, 'i'));
+  return m ? m[1] : undefined;
+}
+/** §31: OPML is XML — reject non-OPML input with a real diagnosis instead of
+ *  silently returning an empty outline (QA-05 F12). Regex-based strictness,
+ *  no XML parser dependency: root element must exist and outline tags must
+ *  balance. Throws Error with an `invalid OPML: …` message. */
+function assertOpml(source: string): void {
+  if (!/<opml[\s>]/i.test(source)) {
+    throw new Error('invalid OPML: missing <opml> root element (not XML)');
+  }
+  if (!/<opml\b[^>]*>[\s\S]*<\/opml\s*>/i.test(source)) {
+    throw new Error('invalid OPML: <opml> element is not closed');
+  }
+  const opens = (source.match(/<outline\b(?![^>]*\/\s*>)[^>]*>/gi) ?? []).length;
+  const closes = (source.match(/<\/outline\s*>/gi) ?? []).length;
+  if (opens !== closes) {
+    throw new Error(`invalid OPML: unbalanced <outline> tags (${opens} opened, ${closes} closed)`);
+  }
+}
+/** Regex-based OPML walk: top level = outlines directly under `<body>`; nesting from tag structure.
+ *  Throws on non-OPML / malformed XML input (see assertOpml). */
+export function parseOpml(source: string): ExternalNode[] {
+  assertOpml(source);
+  const body = source.match(/<body[^>]*>([\s\S]*?)<\/body\s*>/i);
+  const region = body ? body[1] : source;
+  const roots: ExternalNode[] = [];
+  const stack: ExternalNode[] = [];
+  const tag = /<outline\b[^>]*>|<\/outline\s*>/gi;
+  let m: RegExpExecArray | null;
+  while ((m = tag.exec(region)) !== null) {
+    if (m[0][1] === '/') {
+      stack.pop();
+      continue;
+    }
+    const selfClosing = /\/\s*>$/.test(m[0]);
+    const inner = m[0].slice(8, -1);
+    const node: ExternalNode = {
+      text: decodeXmlEntity(readAttr(inner, 'text') ?? ''),
+      indent: stack.length,
+      isTask: false,
+      isDone: false,
+      children: [],
+      metadata: {},
+    };
+    const note = readAttr(inner, '_note') ?? readAttr(inner, 'note');
+    if (note !== undefined) node.metadata.note = decodeXmlEntity(note);
+    (stack.length > 0 ? stack[stack.length - 1].children : roots).push(node);
+    if (!selfClosing) stack.push(node);
+  }
+  return roots;
+}
+/** Accept a tree (children) or a flat indent-based list; rebuild a proper tree for tag nesting. */
+function normalizeTree(nodes: ExternalNode[]): ExternalNode[] {
+  const flat: ExternalNode[] = [];
+  const dfs = (list: ExternalNode[]): void => {
+    for (const n of list) {
+      flat.push(n);
+      dfs(n.children);
+    }
+  };
+  dfs(nodes);
+  const roots: ExternalNode[] = [];
+  const stack: ExternalNode[] = [];
+  for (const n of flat) {
+    const node: ExternalNode = { ...n, children: [] };
+    while (stack.length > 0 && stack[stack.length - 1].indent >= node.indent) stack.pop();
+    (stack.length > 0 ? stack[stack.length - 1].children : roots).push(node);
+    stack.push(node);
+  }
+  return roots;
+}
+/** ExternalNode tree → valid OPML 2.0 document (leaves self-close, parents pair). */
+export function serializeOpml(nodes: ExternalNode[], title: string): string {
+  const outline = (n: ExternalNode, depth: number): string => {
+    const pad = '  '.repeat(depth);
+    const note = n.metadata?.note;
+    // §28: checkbox state survives the round-trip (`- [ ] task` → `- [ ] task` in text)
+    const textContent = n.isTask ? (n.isDone ? '[x] ' : '[ ] ') + n.text : n.text;
+    const attrs = `text="${encodeXmlEntity(textContent)}"${note !== undefined ? ` _note="${encodeXmlEntity(note)}"` : ''}`;
+    if (n.children.length === 0) return `${pad}<outline ${attrs}/>\n`;
+    return `${pad}<outline ${attrs}>\n${n.children.map((c) => outline(c, depth + 1)).join('')}${pad}</outline>\n`;
+  };
+  return (
+    `<?xml version="1.0" encoding="UTF-8"?>\n<opml version="2.0">\n` +
+    `<head><title>${encodeXmlEntity(title)}</title></head>\n<body>\n` +
+    normalizeTree(nodes)
+      .map((n) => outline(n, 1))
+      .join('') +
+    `</body>\n</opml>\n`
+  );
+}

package/src/converters/shared.ts ADDED Viewed

@@ -0,0 +1,268 @@
+import type { ExternalNode } from '../types';
+/** Leading whitespace → indent units. 2 spaces per level; each tab counts as 2 spaces. */
+export function parseIndent(raw: string): number {
+  let spaces = 0;
+  for (const ch of raw) {
+    if (ch === ' ') spaces += 1;
+    else if (ch === '\t') spaces += 2;
+    else break;
+  }
+  return Math.floor(spaces / 2);
+}
+/** Input includes the leading `- ` prefix. `- [ ]`/`- [x]`/`- [X]` and TODO/DOING/DONE markers. */
+export function parseCheckbox(text: string): { isTask: boolean; isDone: boolean; clean: string } {
+  const s = text.replace(/^\s*-\s+/, '');
+  const box = s.match(/^\[([ xX])\]\s?/);
+  if (box) return { isTask: true, isDone: box[1] !== ' ', clean: s.slice(box[0].length).trim() };
+  const kw = s.match(/^(TODO|DOING|DONE)\b\s?/);
+  if (kw) return { isTask: true, isDone: kw[1] === 'DONE', clean: s.slice(kw[0].length).trim() };
+  return { isTask: false, isDone: false, clean: s };
+}
+/** A fenced code block extracted during import into an overflow file (§27). */
+export interface OverflowExtraction {
+  /** Overflow file path relative to the workspace (e.g. `cb-note/request-schema.json`). */
+  overflowFile: string;
+  /** The raw fenced body. */
+  content: string;
+  /** The bullet text the fence hung under. */
+  parentText: string;
+}
+/** `[[X]]` → `see: X.md`; `[[X#Y]]` → `see: X.md#Y`; labels (`|label`) are discarded.
+ *  §4/§27 canonical ref form carries the `.md` suffix — a `.md`-less target is a
+ *  guaranteed broken ref (QA-08 E7). Pages that already name a file with an
+ *  extension (attachments, `X.md`) are kept verbatim. Same-line whitespace right
+ *  after the link is consumed and re-emitted as a single separator, keeping the
+ *  ref token clean and trailing prose as node content (QA-05 F3). Newlines are
+ *  never consumed. */
+export function convertWikiLinks(text: string): string {
+  return text.replace(
+    /\[\[([^[\]|#]*)(?:#([^[\]|#]*))?(?:\|[^[\]]*)?\]\]([ \t]*)/g,
+    (_m, page: string, anchor: string | undefined, trail: string) => {
+      const target = /\.[A-Za-z0-9]{1,8}$/.test(page) ? page : `${page}.md`;
+      const ref = anchor ? `see: ${target}#${anchor}` : `see: ${target}`;
+      return trail.length > 0 ? `${ref} ` : ref;
+    }
+  );
+}
+/** Logseq `[[Page/Anchor]]` is the §28 export encoding of CANS `see: Page.md#Anchor`.
+ *  Rewrite it to `[[Page#Anchor]]` — splitting on the FIRST `/` so `[[X/Y]]` becomes
+ *  page `X`, anchor `Y` — before the generic wiki-link conversion runs (QA-09 D8:
+ *  the slashed form must never leak into the workspace as the dead ref
+ *  `see: X/Y.md`). Plain page links without a slash are untouched. */
+export function logseqSlashLinks(text: string): string {
+  return text.replace(
+    /\[\[([^[\]|#/]+)\/([^[\]|]+?)\]\]/g,
+    (_m, page: string, anchor: string) => `[[${page}#${anchor.trim()}]]`,
+  );
+}
+/** §28 import inverse for owner/gate markers (QA-09 D5): external task-state
+ *  emoji must come back as CANS owner arrows, or round-trips destroy
+ *  owner/gate state. Obsidian: `🤖 agent-1` → `← agent-1`, `⏳ Human` → `← @human`.
+ *  Logseq shares the human-gate row: `⏳ Human` → `← @human`. */
+export function convertOwnerMarkers(text: string, format: string): string {
+  const f = format.toLowerCase();
+  let s = text;
+  if (f === 'obsidian') {
+    s = s.replace(/🤖\s*(\S+)/g, '← $1');
+  }
+  if (f === 'obsidian' || f === 'logseq') {
+    s = s.replace(/⏳\s*Human/i, '← @human');
+  }
+  return s;
+}
+/** Inverse of convertWikiLinks: `see: X.md#Y` → `[[X#Y]]` (`.md` stripped for wiki form). */
+export function reverseWikiLinks(text: string): string {
+  return text.replace(/\bsee:\s+([^\s]+)/g, (_m, target: string) => {
+    const cleaned = target.replace(/\.md(?=#|$)/, '');
+    return `[[${cleaned}]]`;
+  });
+}
+/** Remove app cruft: logseq `key:: value` props, dynalist `^block-ids`, obsidian `#tags`, `*`/`_` emphasis. */
+export function stripMetadata(text: string, format: string): string {
+  const f = format.toLowerCase();
+  const lenient = f !== 'logseq' && f !== 'opml' && f !== 'dynalist' && f !== 'obsidian';
+  let s = text;
+  if (f === 'logseq' || lenient) s = s.replace(/\s*[\w-]+::(?:\s.*|$)/g, '');
+  if (f === 'opml' || f === 'dynalist' || lenient) s = s.replace(/(?:\s*\^[\w-]+)+$/g, '');
+  if (f === 'obsidian' || f === 'dynalist' || lenient) s = s.replace(/(^|\s)#[\w/-]+/g, '$1');
+  s = s
+    .replace(/\*\*\*([^*]+)\*\*\*/g, '$1')
+    .replace(/\*\*([^*]+)\*\*/g, '$1')
+    .replace(/\*([^*]+)\*/g, '$1')
+    .replace(/__([^_]+)__/g, '$1')
+    .replace(/_([^_]+)_/g, '$1');
+  return s.replace(/\s{2,}/g, ' ').trim();
+}
+/** ExternalNode tree → CANS markdown bullets. DFS; each node at `'  '.repeat(node.indent)`. */
+export function serializeToCans(nodes: ExternalNode[]): string {
+  const lines: string[] = [];
+  const walk = (list: ExternalNode[]): void => {
+    for (const n of list) {
+      const box = n.isTask ? (n.isDone ? '[x] ' : '[ ] ') : '';
+      lines.push('  '.repeat(n.indent) + '- ' + box + n.text);
+      // §31: OPML `_note` content is spec content — emit as indented child nodes.
+      if (n.metadata?.note !== undefined && n.metadata.note !== '') {
+        for (const nl of n.metadata.note.split('\n')) {
+          if (nl.trim() === '') continue;
+          lines.push('  '.repeat(n.indent + 1) + '- ' + nl.trim());
+        }
+      }
+      walk(n.children);
+    }
+  };
+  walk(nodes);
+  return lines.length > 0 ? lines.join('\n') + '\n' : '';
+}
+/** CANS markdown → ExternalNode tree (reverse of serializeToCans; stack-attach by indent). */
+export function parseFromCans(source: string): ExternalNode[] {
+  const roots: ExternalNode[] = [];
+  const stack: ExternalNode[] = [];
+  for (const raw of source.split(/\r?\n/)) {
+    const m = raw.match(/^\s*-\s+(.*)$/);
+    if (!m) continue;
+    const { isTask, isDone, clean } = parseCheckbox(raw);
+    const node: ExternalNode = { text: clean, indent: parseIndent(raw), isTask, isDone, children: [], metadata: {} };
+    while (stack.length > 0 && stack[stack.length - 1].indent >= node.indent) stack.pop();
+    (stack.length > 0 ? stack[stack.length - 1].children : roots).push(node);
+    stack.push(node);
+  }
+  return roots;
+}
+function slugFor(text: string): string {
+  return text
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+/** §27 "Extract code blocks → overflow files" (§16: extracted to a separate file
+ *  and referenced via see:). A proper fence state machine — every fence shape
+ *  that appears in imported outline notes is handled, and NO line is ever
+ *  silently dropped (QA-08 E9 / QA-05 F4+F5):
+ *    - plain fence lines (    ```json … ```) hanging under a bullet,
+ *    - fence-as-bullet (`  - ```python … ```) used by Obsidian/Logseq notes,
+ *    - interior lines at any indentation, closing fences at any indentation,
+ *    - unterminated fences at EOF (flushed, not swallowed).
+ *  Each fence is extracted to `<baseSlug>/<node-slug>.<ext>` and replaced by a
+ *  `see:` reference node, so the fence's presence survives and content AFTER
+ *  the closing fence keeps parsing as normal bullets. Returns the cleaned
+ *  bullet source plus the extractions to write. */
+export function extractOverflowContent(
+  source: string,
+  baseSlug: string,
+): { cleanedSource: string; extractions: OverflowExtraction[] } {
+  const lines = source.split(/\r?\n/);
+  const outLines: string[] = [];
+  const extractions: OverflowExtraction[] = [];
+  const usedNames = new Set<string>();
+  let inFence = false;
+  let fenceLang = '';
+  let fenceBody: string[] = [];
+  let fenceAsBullet = false;  // fence opened on a `- ```lang` bullet line
+  let fenceBulletIndent = ''; // indent of that bullet line
+  let lastBulletText = '';    // text of the last bullet seen outside fences
+  let lastBulletIdx = -1;     // index of that bullet within outLines
+  let extractionIndex = 0;
+  /** Overflow paths are workspace-relative and collision-free (two fences under
+   *  the same bullet must never overwrite each other's extraction). */
+  const uniqueOverflowFile = (slug: string, ext: string): string => {
+    let name = `${baseSlug}/${slug}.${ext}`;
+    let n = 2;
+    while (usedNames.has(name)) name = `${baseSlug}/${slug}-${n++}.${ext}`;
+    usedNames.add(name);
+    return name;
+  };
+  /** Close the open fence: extract the body to an overflow file and leave a
+   *  `see:` reference where the fence hung. */
+  const closeFence = (): void => {
+    // Sanitize the fence language into a safe file extension: plain
+    // alphanumerics only (a crafted fence like ``` ../../../evil must
+    // never escape the workspace overflow directory).
+    const rawExt = fenceLang !== '' ? fenceLang : 'md';
+    const ext = /^[A-Za-z0-9]{1,12}$/.test(rawExt) ? rawExt : 'md';
+    const slug = lastBulletText !== '' ? slugFor(lastBulletText) : `block-${extractionIndex}`;
+    const overflowFile = uniqueOverflowFile(slug, ext);
+    extractions.push({
+      overflowFile,
+      content: fenceBody.join('\n'),
+      parentText: lastBulletText,
+    });
+    if (fenceAsBullet) {
+      // The fence was itself a bullet → that bullet becomes the see: reference
+      // node, at the fence bullet's own indent (hierarchy preserved).
+      outLines.push(`${fenceBulletIndent}- see ${overflowFile}`);
+    } else if (lastBulletIdx >= 0 && lastBulletIdx === outLines.length - 1) {
+      // Fence hangs directly under the last bullet → reference replaces it.
+      const indent = outLines[lastBulletIdx].match(/^\s*/)?.[0] ?? '';
+      outLines[lastBulletIdx] = `${indent}- ${lastBulletText}: see ${overflowFile}`;
+    } else {
+      // Fence detached from any bullet → reference after the block.
+      const anchorLine = outLines[outLines.length - 1] ?? '';
+      const indent = anchorLine.match(/^\s*/)?.[0] ?? '';
+      const label = lastBulletText !== '' ? `${lastBulletText}: ` : '';
+      outLines.push(`${indent}- ${label}see ${overflowFile}`);
+    }
+    // A following fence must never clobber the reference just written.
+    lastBulletIdx = -1;
+    extractionIndex++;
+  };
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (inFence) {
+      if (/^`{3,}\s*$/.test(trimmed)) {
+        closeFence();
+        inFence = false;
+        fenceBody = [];
+      } else {
+        fenceBody.push(line);
+      }
+      continue;
+    }
+    // Fence-as-bullet: `- ```lang` — the fence line is itself an outline bullet.
+    const bulletFence = line.match(/^(\s*)-\s+(`{3,}.*)$/);
+    if (bulletFence !== null) {
+      inFence = true;
+      fenceAsBullet = true;
+      fenceBulletIndent = bulletFence[1] ?? '';
+      fenceLang = (bulletFence[2] ?? '').slice(3).trim();
+      fenceBody = [];
+      continue;
+    }
+    // Plain fence line (possibly indented).
+    if (trimmed.startsWith('```')) {
+      inFence = true;
+      fenceAsBullet = false;
+      fenceLang = trimmed.slice(3).trim();
+      fenceBody = [];
+      continue;
+    }
+    const bulletMatch = line.match(/^\s*-\s+(.*)/);
+    if (bulletMatch) {
+      lastBulletText = bulletMatch[1].trim();
+      lastBulletIdx = outLines.length;
+    }
+    outLines.push(line);
+  }
+  if (inFence) {
+    // Unterminated fence at EOF: flush the extraction rather than dropping it.
+    closeFence();
+  }
+  return { cleanedSource: outLines.join('\n'), extractions };
+}

package/src/core/args.ts ADDED Viewed

@@ -0,0 +1,79 @@
+/** Centralized arg parser enforcing §20 contract:
+ *  `--flag value` only. No `--flag=value`, no short flags, no combined flags.
+ *  Unknown flags are errors, not silently ignored. */
+export interface ParsedArgs {
+  positional: string[];
+  flags: Map<string, string | true>;
+  errors: string[];
+}
+export interface FlagSpec {
+  /** flag name without `--` */
+  name: string;
+  /** true = boolean flag (no value), false = requires value */
+  boolean: boolean;
+}
+/**
+ * Parse args against a known flag set.
+ * Returns errors for: unknown flags, `--flag=value` form, short flags,
+ * missing values, combined flags.
+ */
+export function parseArgs(args: string[], spec: FlagSpec[]): ParsedArgs {
+  const known = new Map<string, FlagSpec>();
+  for (const f of spec) known.set(f.name, f);
+  const positional: string[] = [];
+  const flags = new Map<string, string | true>();
+  const errors: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    // Reject --flag=value form
+    if (a.startsWith('--') && a.includes('=')) {
+      errors.push(`invalid flag form "${a}" — use "--${a.slice(2).split('=')[0]} <value>"`);
+      continue;
+    }
+    // Reject short flags / combined flags
+    if (/^-[a-zA-Z]/.test(a) && !a.startsWith('--')) {
+      errors.push(`unknown flag "${a}" — no short flags supported`);
+      continue;
+    }
+    if (a.startsWith('--')) {
+      const name = a.slice(2);
+      const flagSpec = known.get(name);
+      if (flagSpec === undefined) {
+        errors.push(`unknown flag "--${name}"`);
+        continue;
+      }
+      if (flagSpec.boolean) {
+        flags.set(name, true);
+      } else {
+        const val = args[i + 1];
+        if (val === undefined || val.startsWith('--')) {
+          errors.push(`flag "--${name}" requires a value`);
+        } else {
+          flags.set(name, val);
+          i++; // consume value
+        }
+      }
+      continue;
+    }
+    positional.push(a);
+  }
+  return { positional, flags, errors };
+}
+/** Format arg errors per §37: what / where / what to do — WITHOUT the `✗` mark
+ *  (error fields carry raw text; the human printer adds the mark). */
+export function formatArgErrors(errors: string[], command: string): string {
+  return errors
+    .map(e => `${e}\n  Run \`cans help\` for valid ${command} flags.`)
+    .join('\n');
+}