@jeremiewerner/motto 0.0.3

package/src/lint.js

@@ -0,0 +1,207 @@
+/**
+ * Motto lint orchestrator.
+ *
+ * Exports a single async function `lintProject(projectRoot)` that wires the
+ * Phase 1 pure validators (parseFrontmatter, validateSkill, loadConfig) to the
+ * filesystem: it discovers skills and shared references on disk, reads each
+ * SKILL.md, runs the pure validators, and aggregates all errors across all
+ * skills before returning.
+ *
+ * Per D-01 / D2-06: lintProject NEVER throws at its boundary. Every I/O or
+ * parse error is converted to a `{ skill, message }` entry and the scan
+ * continues to all remaining skills.
+ *
+ * Return shape: { ok: boolean, errors: Array<{ skill: string, message: string }>, count: number }
+ *   ok     — true when errors is empty.
+ *   errors — aggregated error list; config errors (labelled 'motto.yaml') always
+ *            precede skill errors; skill errors are in alphabetical-by-dirName order.
+ *   count  — number of skills discovered (0 when none found).
+ *
+ * Internal helpers (not exported): processConfig, loadSharedRefs,
+ * discoverSkillNames, processSkill — per RESEARCH Module Decomposition
+ * Recommendation.
+ */
+
+import { readFile, readdir } from 'node:fs/promises';
+import { join, basename, extname } from 'node:path';
+
+import { parseFrontmatter } from './frontmatter.js';
+import { validateSkill } from './schema.js';
+import { loadConfig } from './config.js';
+
+// ---------------------------------------------------------------------------
+// processConfig — step 1 of lintProject (D2-09, D2-10)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read and validate motto.yaml. Any error is pushed to the shared `errors`
+ * array under the `'motto.yaml'` label (D2-10). Never throws; always returns.
+ *
+ * @param {string} projectRoot
+ * @param {Array<{skill: string, message: string}>} errors - mutated in place
+ */
+async function processConfig(projectRoot, errors) {
+  const configPath = join(projectRoot, 'motto.yaml');
+  let text;
+  try {
+    text = await readFile(configPath, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      errors.push({ skill: 'motto.yaml', message: 'file not found' });
+    } else {
+      errors.push({ skill: 'motto.yaml', message: `could not read: ${e.message}` });
+    }
+    return; // config errors collected; skill scan still runs (D2-10)
+  }
+  const { errors: configErrors } = loadConfig(text);
+  for (const e of configErrors) {
+    // Lift: loadConfig errors have no skill field (Pitfall 3); add 'motto.yaml' label
+    errors.push({ skill: 'motto.yaml', message: e.message });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// loadSharedRefs — step 2 of lintProject (D2-07, D2-08)
+// ---------------------------------------------------------------------------
+
+/**
+ * Scan shared/references/*.md and return a Set of basenames (without .md).
+ * A missing shared/ or shared/references/ directory is NOT an error — returns
+ * an empty Set (D2-08). Other unexpected I/O errors are rethrown.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<Set<string>>}
+ */
+async function loadSharedRefs(projectRoot) {
+  const refsDir = join(projectRoot, 'shared', 'references');
+  try {
+    const entries = await readdir(refsDir, { withFileTypes: true });
+    return new Set(
+      entries
+        .filter((e) => e.isFile() && extname(e.name) === '.md')
+        .map((e) => basename(e.name, '.md')),
+    );
+  } catch (e) {
+    if (e.code === 'ENOENT') return new Set(); // D2-08: absence is not an error
+    throw e; // unexpected — propagate to the lintProject boundary
+  }
+}
+
+// ---------------------------------------------------------------------------
+// discoverSkillNames — step 3 of lintProject (D2-02, D2-03, D2-04)
+// ---------------------------------------------------------------------------
+
+/**
+ * Discover candidate skill directories under `skillsDir` (one level deep).
+ *
+ * Filters: non-hidden directories only (D2-04).
+ * Sort: localeCompare for deterministic alphabetical order (D2-03, Pitfall 1).
+ *
+ * Returns `null`  when skillsDir is missing (ENOENT) — caller maps to "no skills found".
+ * Returns `[]`    when skillsDir exists but contains no candidates — same treatment.
+ * Rethrows any other I/O error.
+ *
+ * @param {string} skillsDir - absolute path to the skills/ directory
+ * @returns {Promise<string[]|null>}
+ */
+async function discoverSkillNames(skillsDir) {
+  let entries;
+  try {
+    entries = await readdir(skillsDir, { withFileTypes: true });
+  } catch (e) {
+    if (e.code === 'ENOENT') return null; // caller converts to "no skills found"
+    throw e;
+  }
+  return entries
+    .filter((e) => e.isDirectory() && !e.name.startsWith('.')) // D2-04
+    .sort((a, b) => a.name.localeCompare(b.name)) // D2-03 — MANDATORY (Pitfall 1)
+    .map((e) => e.name);
+}
+
+// ---------------------------------------------------------------------------
+// processSkill — step 4 helper (D2-05, D2-06)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read and validate a single skill directory. Errors are pushed to the shared
+ * `errors` array. Any unexpected exception is caught and converted to an error
+ * entry so the scan ALWAYS continues (D2-06 backstop).
+ *
+ * @param {string} skillsDir
+ * @param {string} dirName
+ * @param {Set<string>} sharedRefs
+ * @param {Array<{skill: string, message: string}>} errors - mutated in place
+ */
+async function processSkill(skillsDir, dirName, sharedRefs, errors) {
+  try {
+    const skillPath = join(skillsDir, dirName, 'SKILL.md');
+    let text;
+    try {
+      text = await readFile(skillPath, 'utf8');
+    } catch (e) {
+      if (e.code === 'ENOENT') {
+        // D2-05: missing SKILL.md is a hard error; report it and move on
+        errors.push({ skill: dirName, message: 'missing SKILL.md' });
+      } else {
+        errors.push({ skill: dirName, message: `could not read SKILL.md: ${e.message}` });
+      }
+      return; // return from helper == continue in the outer loop (Pitfall 5)
+    }
+
+    // Parse frontmatter — never throws (D-01)
+    const { data, body, errors: parseErrors } = parseFrontmatter(text);
+    // Lift parseFrontmatter errors: no skill field in returned errors (Pitfall 2)
+    for (const e of parseErrors) {
+      errors.push({ skill: dirName, message: e.message });
+    }
+
+    // Schema validation — already returns { skill, message } shaped (already normalized)
+    const schemaErrors = validateSkill({ dirName, data, body }, sharedRefs);
+    errors.push(...schemaErrors);
+  } catch (e) {
+    // Backstop: any unexpected failure during per-skill I/O or validation (D2-06)
+    errors.push({ skill: dirName, message: `unexpected error: ${e.message}` });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// lintProject — main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Lint a Motto project rooted at `projectRoot`.
+ *
+ * Execution order (locked per D2-10 — config errors MUST precede skill errors):
+ *   1. processConfig  — reads motto.yaml; errors labelled 'motto.yaml'
+ *   2. loadSharedRefs — scans shared/references/*.md → Set of basenames
+ *   3. discoverSkillNames — reads skills/ directory; null or [] → "no skills found"
+ *   4. processSkill (each, in sorted order) — reads + validates each SKILL.md
+ *
+ * @param {string} projectRoot - absolute path to the project root
+ * @returns {Promise<{ ok: boolean, errors: Array<{skill: string, message: string}>, count: number }>}
+ */
+export async function lintProject(projectRoot) {
+  const errors = [];
+
+  // 1. Config errors first so they precede all skill errors (D2-10)
+  await processConfig(projectRoot, errors);
+
+  // 2. Shared references set (empty if shared/ missing — D2-08)
+  const sharedRefs = await loadSharedRefs(projectRoot);
+
+  // 3. Discover skills — null = ENOENT, [] = empty dir; both map to "no skills found" (D2-13, Pitfall 9)
+  const skillsDir = join(projectRoot, 'skills');
+  const skillNames = await discoverSkillNames(skillsDir);
+
+  if (skillNames === null || skillNames.length === 0) {
+    errors.push({ skill: '(project)', message: 'no skills found' });
+    return { ok: false, errors, count: 0 };
+  }
+
+  // 4. Process each skill in the sorted (alphabetical) order returned by discoverSkillNames
+  for (const dirName of skillNames) {
+    await processSkill(skillsDir, dirName, sharedRefs, errors);
+  }
+
+  return { ok: errors.length === 0, errors, count: skillNames.length };
+}

package/src/schema.js

@@ -0,0 +1,170 @@
+/**
+ * Motto skill-schema validator.
+ *
+ * Pure object validator — no filesystem, no YAML parsing, no imports beyond
+ * this file's own scope. NEVER throws (D-01). All validation failures surface
+ * through the returned errors[].
+ *
+ * Exports:
+ *   - NAME_KEBAB {RegExp}  — canonical letter-start kebab regex (D-08, D-16)
+ *   - validateSkill(skill, sharedRefs?) -> Array<{ skill, message }>
+ */
+
+/**
+ * Canonical letter-start kebab-case regex for skill and plugin names.
+ *
+ * Pattern: /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
+ *   - starts with exactly one lowercase letter (letter-start — D-08 fix; the
+ *     prior-art /^[a-z0-9]+/ wrongly allowed a leading digit)
+ *   - followed by zero or more lowercase letters or digits
+ *   - then zero or more groups of (one hyphen + one or more lowercase letters/digits)
+ *
+ * Valid examples:   "my-skill", "abc", "a1", "abc-def-123"
+ * Invalid examples: "0bad" (leading digit), "My_Skill" (uppercase/underscore),
+ *                   "my--skill" (double dash), "-bad" (leading dash), "bad-" (trailing dash)
+ *
+ * Anchored and unambiguous — no catastrophic backtracking (T-02-01): each `-`
+ * unambiguously opens exactly one group; `-` cannot appear in [a-z0-9].
+ *
+ * Exported so src/config.js can reuse the same regex without diverging (D-16).
+ *
+ * @type {RegExp}
+ */
+export const NAME_KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+/**
+ * Reserved substrings that must not appear in skill or plugin names (LINT-02, D-09).
+ * @type {string[]}
+ */
+const RESERVED = ["anthropic", "claude"];
+
+/**
+ * Validate a parsed skill object against the Motto schema.
+ *
+ * Error-aggregation model (D-13):
+ *   - NAME checks CASCADE: missing/falsy → non-string → non-kebab → max-64 → reserved-word → ≠folder.
+ *     The chain stops at the first failure; subsequent name checks are skipped
+ *     because they are meaningless once an earlier check fails.
+ *   - All OTHER checks (description, audience, body Title, body Role, each
+ *     shared_references entry) are INDEPENDENT: they all run and all errors
+ *     are collected together regardless of what other checks find.
+ *
+ * Unknown frontmatter keys (`template`, `dependencies`, …) are accepted
+ * without error (D-14).
+ *
+ * @param {{ dirName: string, data: object, body: string }} skill
+ *   `dirName` — the skill's source folder name (cascade anchor + error.skill)
+ *   `data`    — parsed YAML frontmatter object (plain JS; never mutated)
+ *   `body`    — Markdown body string after the closing `---` delimiter
+ * @param {Set<string>} [sharedRefs]
+ *   Set of available shared-reference basenames (without `.md`). Defaults to
+ *   an empty Set; entries in data.shared_references are resolved against it.
+ * @returns {Array<{ skill: string, message: string }>}
+ *   Empty array when the skill is fully valid; one object per error otherwise.
+ *   Each object's `skill` field equals `dirName`.
+ */
+export function validateSkill(skill, sharedRefs = new Set()) {
+  const { dirName, data, body } = skill;
+  const errors = [];
+
+  /** Push one error attributed to this skill's dirName. */
+  const err = (message) => errors.push({ skill: dirName, message });
+
+  // ── NAME (cascade — D-08, D-09, D-13) ─────────────────────────────────────
+  // Stop at the first failure. Do NOT accumulate multiple name errors.
+  const name = data.name;
+  if (!name) {
+    // Step 1: missing / empty / falsy name (false, 0, "", null, undefined)
+    err("name is required");
+  } else if (typeof name !== "string") {
+    // Step 2: non-string truthy name (e.g. YAML boolean true, number 123, array, object).
+    // Must guard BEFORE NAME_KEBAB.test() and RESERVED.includes() — both coerce and
+    // may throw (`.includes` is not defined on booleans). D-01: never throw. (REVIEW-01)
+    err(`name must be a string (got ${typeof name})`);
+  } else if (!NAME_KEBAB.test(name)) {
+    // Step 3: not letter-start kebab-case (D-08)
+    err(
+      `name must be letter-start kebab-case (/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/): "${name}"`
+    );
+  } else if (name.length > 64) {
+    // Step 3: name exceeds maximum length of 64 characters (D-03)
+    err(`name must not exceed 64 characters (got ${name.length}): "${name}"`);
+  } else if (RESERVED.some((r) => name.includes(r))) {
+    // Step 4: contains a reserved substring (D-09)
+    err(
+      `name must not contain the reserved substrings "anthropic" or "claude": "${name}"`
+    );
+  } else if (name !== dirName) {
+    // Step 5: name does not match folder
+    err(`name "${name}" must equal its folder name "${dirName}"`);
+  }
+
+  // ── DESCRIPTION (LINT-01, independent) ────────────────────────────────────
+  if (!data.description) {
+    err("description is required");
+  } else {
+    // Both checks run independently — neither guards the other (D-13).
+    // Guards are inside the else branch so a falsy description cannot throw (D-01).
+    if (data.description.length > 1024) {
+      // D-03: description must not exceed 1024 characters
+      err(
+        `description must not exceed 1024 characters (got ${data.description.length})`
+      );
+    }
+    // D-05: description must not contain XML-tag shapes. Pattern matches only
+    // real tag-like constructs (optional leading /, letter-led tag name,
+    // optional trailing whitespace + optional self-close /, then >) so that
+    // ordinary comparison/math prose like "a<b and b>c" is NOT flagged.
+    // Adjacent quantifiers cover disjoint character classes ([a-zA-Z0-9-] vs \s)
+    // — no catastrophic backtracking (T-Q-01). (REVIEW-04)
+    if (/<\/?[a-zA-Z][a-zA-Z0-9-]*\s*\/?>/.test(data.description)) {
+      err("description must not contain XML tags (e.g. <example>)");
+    }
+  }
+
+  // ── AUDIENCE (LINT-03, D-11, independent) ─────────────────────────────────
+  // Missing and invalid values both produce the same error message (D-11).
+  if (data.audience !== "public" && data.audience !== "private") {
+    err("audience must be public|private");
+  }
+
+  // ── BODY SPINE (LINT-04, D-12) — two INDEPENDENT checks ──────────────────
+  const bodyStr = body || "";
+  const bodyLines = bodyStr.split("\n");
+
+  // Title check: the first non-blank line must be an H1 ("# " + non-space char).
+  // Regex is anchored and linear-time (T-02-01).
+  const firstNonBlankLine = bodyLines.find((l) => l.trim() !== "");
+  if (!firstNonBlankLine || !/^# \S/.test(firstNonBlankLine)) {
+    err(
+      "body must begin with an H1 title line (# Title) as its first non-blank line"
+    );
+  }
+
+  // Role check: body must contain at least one line starting with "**Role:".
+  // Anchored multiline regex; `^` matches start of any line with the `m` flag (T-02-01).
+  if (!/^\*\*Role:/m.test(bodyStr)) {
+    err("body must contain a **Role:** line");
+  }
+
+  // ── SHARED_REFERENCES (LINT-05, D-10) — each entry is independent ─────────
+  // For each entry, the safe-basename check runs FIRST (D-10): if the entry
+  // contains "/" or ".", it is immediately flagged as an unsafe path reference
+  // and the membership check is skipped for that entry. This prevents a
+  // malicious reference from escaping shared/references/ in the build step
+  // (T-02-02).
+  const refs = Array.isArray(data.shared_references) ? data.shared_references : [];
+  for (const entry of refs) {
+    if (typeof entry === "string" && (entry.includes("/") || entry.includes("."))) {
+      // Unsafe basename: contains a path separator or extension dot.
+      err(
+        `shared_references entry "${entry}" is an unsafe basename (must not contain "/" or ".")`
+      );
+    } else if (!sharedRefs.has(entry)) {
+      // Safe basename but not in the available set.
+      err(`shared_references entry "${entry}" not found in shared/references/`);
+    }
+  }
+
+  return errors;
+}