@seanmars/tospec 0.19.0-beta.7 → 0.20.0

package/dist/core/artifact-graph/outputs.js

@@ -2,9 +2,6 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import fg from 'fast-glob';
 import { FileSystemUtils } from '../../utils/file-system.js';
-/**
- * Checks if a path contains glob pattern characters.
- */
 export function isGlobPattern(pattern) {
     return pattern.includes('*') || pattern.includes('?') || pattern.includes('[');
 }
@@ -12,17 +9,13 @@ export function isGlobPattern(pattern) {
  * A pattern whose wildcard occupies exactly one whole path segment, with every
  * other segment literal — `specs/*` or `specs/<*>/spec.md`.
  *
- * This is the only glob shape any shipped schema declares (`specs/*<!---->/spec.md`, in
- * both `sdd` and `issue`), and the delta-spec layout is fixed at exactly one
- * directory level, so it is the only shape that occurs in practice. Answering it
- * with `readdir` + `stat` skips a general glob engine's per-call pattern
- * compilation and stream setup — the dominant cost on the dashboard's hot path,
- * where the whole aggregation re-runs on every file save.
+ * The only glob shape any shipped schema declares. Answering it with `readdir` +
+ * `stat` skips a glob engine's per-call pattern compilation and stream setup —
+ * the dominant cost on the dashboard's hot path, which re-runs the whole
+ * aggregation on every file save.
  *
- * Returns `null` when the pattern is any other shape, so the caller falls back
- * to fast-glob. `generates` is schema-authored and a user schema may declare
- * something this cannot express; the fast path is an optimisation, not a
- * narrowing of the contract.
+ * `null` for any other shape, so the caller falls back to fast-glob: the fast
+ * path is an optimisation, not a narrowing of the contract.
  */
 function splitSingleWildcard(generates) {
     const segments = FileSystemUtils.toPosixPath(generates).split('/');
@@ -40,16 +33,40 @@ function splitSingleWildcard(generates) {
         return null;
     return { prefix: segments.slice(0, wildcardIndex), suffix: segments.slice(wildcardIndex + 1) };
 }
-/** Shared tail so the sync and async resolvers cannot drift in how they finish. */
+/** Shared tail, so the sync and async resolvers finish identically. */
 function finalizeMatches(matches) {
     return Array.from(new Set(matches)).sort();
 }
+/**
+ * Whether each fixed segment after the wildcard is spelled on disk exactly as
+ * the pattern spells it. `stat` answers case-insensitively on Windows and
+ * macOS while fast-glob matches names literally, so without this the fast
+ * path counted `SPEC.MD` as done and the glob path did not.
+ */
+function hasExactSuffixSpelling(dir, suffix) {
+    let current = dir;
+    for (const segment of suffix) {
+        if (!fs.readdirSync(current).includes(segment))
+            return false;
+        current = path.join(current, segment);
+    }
+    return true;
+}
+async function hasExactSuffixSpellingAsync(dir, suffix) {
+    let current = dir;
+    for (const segment of suffix) {
+        if (!(await fs.promises.readdir(current)).includes(segment))
+            return false;
+        current = path.join(current, segment);
+    }
+    return true;
+}
 function globFallbackOptions(changeDir) {
     return { cwd: changeDir, onlyFiles: true, absolute: true };
 }
 /**
- * Resolves an artifact's output path(s) to concrete files that currently exist.
- * Returns absolute file paths. Glob matches are sorted for deterministic output.
+ * Absolute paths of the files an artifact's `generates` currently resolves to.
+ * Sorted, for deterministic output.
  */
 export function resolveArtifactOutputs(changeDir, generates) {
     if (!isGlobPattern(generates)) {
@@ -81,10 +98,10 @@ export function resolveArtifactOutputs(changeDir, generates) {
                 continue;
             const candidate = path.join(baseDir, entry, ...single.suffix);
             try {
-                // statSync (not the Dirent type) so symlinks resolve the way fast-glob's
-                // default followSymbolicLinks does, and so `onlyFiles` still holds for a
+                // statSync, not the Dirent type, so symlinks resolve as fast-glob's
+                // default followSymbolicLinks does and `onlyFiles` still holds for a
                 // *directory* named spec.md.
-                if (fs.statSync(candidate).isFile()) {
+                if (fs.statSync(candidate).isFile() && hasExactSuffixSpelling(path.join(baseDir, entry), single.suffix)) {
                     matches.push(FileSystemUtils.canonicalizeExistingPath(candidate));
                 }
             }
@@ -101,24 +118,16 @@ export function resolveArtifactOutputs(changeDir, generates) {
     return finalizeMatches(matches);
 }
 /**
- * Async twin of {@link resolveArtifactOutputs}, for `collectChangeDetail` — its
- * only caller, and the reason it is worth keeping a second implementation.
- * A detail pane is fetched while the overview may still be aggregating, so its
- * per-artifact resolution is the one that has something to interleave with.
+ * Async twin of {@link resolveArtifactOutputs}, for `collectChangeDetail`: a
+ * detail pane is fetched while the overview may still be aggregating, so it has
+ * something to interleave with.
  *
- * It does **not** serve the save-triggered overview, despite what the change
- * that introduced it was named after. `collectOverview` reaches this module only
- * through `artifactSummaryFor` → `formatChangeStatus` → `artifactOutputExists`
- * and through `listTasksForChange`, both synchronous — deliberately, and
- * measured: dashboard-data.ts records 2.1 ms as the longest stall across 30
- * changes with the sync resolver in place, because the awaits already sitting in
- * that loop break the work across iterations. What removed the cost there was
- * the single-wildcard `readdir` fast path above, not asynchrony.
+ * It does **not** serve the save-triggered overview, which reaches this module
+ * only through synchronous paths — see the measurement in dashboard-data.ts.
  *
  * The duplicated branch structure is held to the sync version by the parity
- * cases in test/core/artifact-graph/outputs.test.ts, which run both resolvers
- * over each branch — non-glob, fast path, fast-glob fallback, missing prefix —
- * and assert identical results. Any behaviour added to one belongs in that list.
+ * cases in test/core/artifact-graph/outputs.test.ts. Any behaviour added to one
+ * belongs in that list.
  */
 export async function resolveArtifactOutputsAsync(changeDir, generates) {
     if (!isGlobPattern(generates)) {
@@ -147,7 +156,8 @@ export async function resolveArtifactOutputsAsync(changeDir, generates) {
                 return null;
             const candidate = path.join(baseDir, entry, ...single.suffix);
             try {
-                return (await fs.promises.stat(candidate)).isFile()
+                return (await fs.promises.stat(candidate)).isFile() &&
+                    (await hasExactSuffixSpellingAsync(path.join(baseDir, entry), single.suffix))
                     ? FileSystemUtils.canonicalizeExistingPath(candidate)
                     : null;
             }
@@ -161,9 +171,6 @@ export async function resolveArtifactOutputsAsync(changeDir, generates) {
     const matches = (await fg(normalizedPattern, globFallbackOptions(changeDir))).map((match) => FileSystemUtils.canonicalizeExistingPath(path.normalize(match)));
     return finalizeMatches(matches);
 }
-/**
- * Checks if an artifact has at least one resolved output file.
- */
 export function artifactOutputExists(changeDir, generates) {
     return resolveArtifactOutputs(changeDir, generates).length > 0;
 }

package/dist/core/artifact-graph/outputs.js.map

@@ -1 +1 @@
-{"version":3,"file":"outputs.js","sourceRoot":"","sources":["../../../src/core/artifact-graph/outputs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"outputs.js","sourceRoot":"","sources":["../../../src/core/artifact-graph/outputs.ts"],"names":[],"mappings":"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"}

package/dist/core/artifact-graph/resolver.d.ts

@@ -1,17 +1,11 @@
 import * as fs from 'node:fs';
 import type { SchemaYaml } from './types.js';
-/**
- * Error thrown when loading a schema fails.
- */
 export declare class SchemaLoadError extends Error {
     readonly schemaPath: string;
     readonly cause?: Error | undefined;
     constructor(message: string, schemaPath: string, cause?: Error | undefined);
 }
-/**
- * Gets the package's built-in schemas directory path.
- * Uses import.meta.url to resolve relative to the current module.
- */
+/** Walks up from dist/core/artifact-graph/ to the package root's schemas/. */
 export declare function getPackageSchemasDir(): string;
 /**
  * The user's schema override directory: inside the config directory, unless
@@ -19,70 +13,50 @@ export declare function getPackageSchemasDir(): string;
  * than adding to it, so exactly one user-level override directory is ever live.
  */
 export declare function getUserSchemasDir(): string;
-/**
- * Gets the project-local schemas directory path.
- * @param projectRoot - The project root directory
- * @returns The path to the project's schemas directory
- */
 export declare function getProjectSchemasDir(projectRoot: string): string;
 /**
- * Whether a directory entry is a schema-directory candidate. Returns true for
- * real directories and for symlinks whose target is a directory. `Dirent`'s
- * `isDirectory()` reports the raw entry type, so a symlink pointing at a
- * directory has `isDirectory() === false`; such entries are dereferenced via
- * `statSync` to admit symlinked schema dirs while still rejecting
- * symlinks-to-files and broken/dangling links.
+ * True for real directories and for symlinks pointing at one. `Dirent`'s
+ * `isDirectory()` reports the raw entry type, so a symlinked schema dir needs
+ * the `statSync` dereference below.
  */
 export declare function isSchemaDir(parentDir: string, entry: fs.Dirent): boolean;
-/**
- * Resolves a schema name to its directory path.
- *
- * Resolution order (when projectRoot is provided):
- * 1. Project-local: <projectRoot>/tospec/schemas/<name>/schema.yaml
- * 2. User override: ${XDG_DATA_HOME}/tospec/schemas/<name>/schema.yaml
- * 3. Package built-in: <package>/schemas/<name>/schema.yaml
- *
- * When projectRoot is not provided, only user override and package built-in are checked
- * (backward compatible behavior).
- *
- * @param name - Schema name (e.g., "sdd")
- * @param projectRoot - Optional project root directory for project-local schema resolution
- * @returns The path to the schema directory, or null if not found
- */
 /**
  * Identity of a file's current contents, for cache invalidation. Null when the
  * file cannot be stat'd, which disables caching for that path rather than
  * risking a stale hit.
  */
 export declare function fileStamp(filePath: string): string | null;
-export declare function getSchemaDir(name: string, projectRoot?: string): string | null;
 /**
- * Resolves a schema name to a SchemaYaml object.
- *
- * Resolution order (when projectRoot is provided):
- * 1. Project-local: <projectRoot>/tospec/schemas/<name>/schema.yaml
- * 2. User override: ${XDG_DATA_HOME}/tospec/schemas/<name>/schema.yaml
- * 3. Package built-in: <package>/schemas/<name>/schema.yaml
+ * The directory holding `<name>/schema.yaml` and the layer it came from, or
+ * null when no layer has one. Project-local wins over the user override, which
+ * wins over the package built-in; without `projectRoot` only the last two are
+ * searched.
  *
- * When projectRoot is not provided, only user override and package built-in are checked
- * (backward compatible behavior).
- *
- * @param name - Schema name (e.g., "sdd")
- * @param projectRoot - Optional project root directory for project-local schema resolution
- * @returns The resolved schema object
- * @throws Error if schema is not found in any location
+ * The layer is resolved here rather than re-derived from the path by each
+ * caller: a directory is the *whole* schema, templates included, so "which layer
+ * won" is what explains a file the winning layer does not have.
  */
-export declare function resolveSchema(name: string, projectRoot?: string): SchemaYaml;
+export declare function getSchemaDirWithSource(name: string, projectRoot?: string): {
+    dir: string;
+    source: SchemaInfo['source'];
+} | null;
+/** As `getSchemaDirWithSource`, for callers that only need the path. */
+export declare function getSchemaDir(name: string, projectRoot?: string): string | null;
 /**
- * Lists all available schema names.
- * Combines project-local, user override, and package built-in schemas.
+ * The parsed schema, resolved through `getSchemaDir`'s precedence order.
  *
- * @param projectRoot - Optional project root directory for project-local schema resolution
+ * @throws SchemaLoadError when the file cannot be read or does not parse.
  */
+export declare function resolveSchema(name: string, projectRoot?: string): SchemaYaml;
+/** Every schema name on disk across all three layers. */
 export declare function listSchemas(projectRoot?: string): string[];
 /**
- * Schema info with metadata (name, description, artifacts).
+ * Names of the schemas that actually load — what an "Available schemas:" list
+ * has to mean. `listSchemas` reports directory names, so a schema.yaml with a
+ * typo in it would be offered as a choice. Anything phrased as advice to the
+ * user belongs here.
  */
+export declare function listLoadableSchemas(projectRoot?: string): string[];
 export interface SchemaInfo {
     name: string;
     description: string;
@@ -90,28 +64,35 @@ export interface SchemaInfo {
     source: 'project' | 'user' | 'package';
     /**
      * Absolute path to the directory holding schema.yaml (and its templates/).
-     * `source` says which of the three layers won; this says which file to open —
-     * the question a schema author actually has when a resolution surprises them.
+     * `source` says which of the three layers won; this says which file to open.
      */
     path: string;
+    /**
+     * Why this schema could not be loaded, on a broken entry only (which also has
+     * an empty `artifacts` list). Carrying the failure in place rather than
+     * dropping the entry is the same rule `list` follows for an unreadable change:
+     * tospec/decisions/20260917_234821-batch-commands-degrade-per-item.md
+     */
+    error?: string;
 }
 /**
- * Lists all available schemas with their descriptions and artifact lists.
- * Useful for agent skills to present schema selection to users.
+ * Every schema with its description and artifact list, for agent skills that
+ * present a schema choice.
  *
- * @param projectRoot - Optional project root directory for project-local schema resolution
+ * A schema that fails to parse is reported with `error` set, but only when no
+ * lower-precedence layer supplies a working schema of that name — a broken
+ * project override must not hide the package schema it shadows.
  */
 export declare function listSchemasWithInfo(projectRoot?: string): SchemaInfo[];
 /**
  * Union of every artifact ID across every available schema.
  *
- * Config keys that are scoped per-artifact but stored globally (`rules:`) can
- * legitimately name an artifact from any schema, so they must be checked
- * against the union rather than whichever schema the current change uses.
+ * Config keys scoped per-artifact but stored globally (`rules:`) can
+ * legitimately name an artifact from any schema, so they are checked against the
+ * union rather than the current change's schema.
  *
- * Built on listSchemasWithInfo so it inherits that function's precedence
- * handling and its tolerance for a schema that fails to parse — one broken
- * custom schema must not turn every rules key into an unknown ID.
+ * Built on listSchemasWithInfo to inherit its tolerance for a schema that fails
+ * to parse: one broken custom schema must not turn every rules key unknown.
  */
 export declare function collectAllArtifactIds(projectRoot?: string): Set<string>;
 //# sourceMappingURL=resolver.d.ts.map

package/dist/core/artifact-graph/resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../../src/core/artifact-graph/resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAK9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;aAGtB,UAAU,EAAE,MAAM;aAClB,KAAK,CAAC,EAAE,KAAK;IAH/B,YACE,OAAO,EAAE,MAAM,EACC,UAAU,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,KAAK,YAAA,EAI9B;CACF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAI7C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAK1C;AAWD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,GAAG,OAAO,CAYxE;AAED;;;;;;;;;;;;;;GAcG;AACH;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOzD;AAoCD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,GAAG,IAAI,CASf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU,CA0D5E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ1D;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IACvC;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE,CA2BtE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAEvE"}
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../../src/core/artifact-graph/resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAK9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,qBAAa,eAAgB,SAAQ,KAAK;aAGtB,UAAU,EAAE,MAAM;aAClB,KAAK,CAAC,EAAE,KAAK;IAH/B,YACE,OAAO,EAAE,MAAM,EACC,UAAU,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,KAAK,YAAA,EAI9B;CACF;AAED,8EAA8E;AAC9E,wBAAgB,oBAAoB,IAAI,MAAM,CAG7C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAK1C;AAUD,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,GAAG,OAAO,CAYxE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOzD;AA+CD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,GACnB;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAA;CAAE,GAAG,IAAI,CAStD;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,GAAG,IAAI,CAEf;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU,CA+C5E;AAED,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ1D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAIlE;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IACvC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE,CAuCtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAEvE"}

package/dist/core/artifact-graph/resolver.js

@@ -3,9 +3,6 @@ import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getGlobalConfigDir, getLegacyDataDir } from '../global-config.js';
 import { parseSchema, SchemaValidationError } from './schema.js';
-/**
- * Error thrown when loading a schema fails.
- */
 export class SchemaLoadError extends Error {
     schemaPath;
     cause;
@@ -16,13 +13,9 @@ export class SchemaLoadError extends Error {
         this.name = 'SchemaLoadError';
     }
 }
-/**
- * Gets the package's built-in schemas directory path.
- * Uses import.meta.url to resolve relative to the current module.
- */
+/** Walks up from dist/core/artifact-graph/ to the package root's schemas/. */
 export function getPackageSchemasDir() {
     const currentFile = fileURLToPath(import.meta.url);
-    // Navigate from dist/core/artifact-graph/ to package root's schemas/
     return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas');
 }
 /**
@@ -38,27 +31,18 @@ export function getUserSchemasDir() {
 }
 /**
  * Where overrides sit until an install migrates. Ranked below the current user
- * directory, so a migrated copy wins and a not-yet-migrated one still applies —
- * per schema name, because every lookup walks this list name by name.
+ * directory, so a migrated copy wins and a not-yet-migrated one still applies.
  */
 function getLegacySchemasDir() {
     return path.join(getLegacyDataDir(), 'schemas');
 }
-/**
- * Gets the project-local schemas directory path.
- * @param projectRoot - The project root directory
- * @returns The path to the project's schemas directory
- */
 export function getProjectSchemasDir(projectRoot) {
     return path.join(projectRoot, 'tospec', 'schemas');
 }
 /**
- * Whether a directory entry is a schema-directory candidate. Returns true for
- * real directories and for symlinks whose target is a directory. `Dirent`'s
- * `isDirectory()` reports the raw entry type, so a symlink pointing at a
- * directory has `isDirectory() === false`; such entries are dereferenced via
- * `statSync` to admit symlinked schema dirs while still rejecting
- * symlinks-to-files and broken/dangling links.
+ * True for real directories and for symlinks pointing at one. `Dirent`'s
+ * `isDirectory()` reports the raw entry type, so a symlinked schema dir needs
+ * the `statSync` dereference below.
  */
 export function isSchemaDir(parentDir, entry) {
     if (entry.isDirectory()) {
@@ -74,21 +58,6 @@ export function isSchemaDir(parentDir, entry) {
     }
     return false;
 }
-/**
- * Resolves a schema name to its directory path.
- *
- * Resolution order (when projectRoot is provided):
- * 1. Project-local: <projectRoot>/tospec/schemas/<name>/schema.yaml
- * 2. User override: ${XDG_DATA_HOME}/tospec/schemas/<name>/schema.yaml
- * 3. Package built-in: <package>/schemas/<name>/schema.yaml
- *
- * When projectRoot is not provided, only user override and package built-in are checked
- * (backward compatible behavior).
- *
- * @param name - Schema name (e.g., "sdd")
- * @param projectRoot - Optional project root directory for project-local schema resolution
- * @returns The path to the schema directory, or null if not found
- */
 /**
  * Identity of a file's current contents, for cache invalidation. Null when the
  * file cannot be stat'd, which disables caching for that path rather than
@@ -105,6 +74,16 @@ export function fileStamp(filePath) {
 }
 /** Parsed schemas keyed by path, invalidated when the file's stamp changes. */
 const schemaCache = new Map();
+/**
+ * One wording for a schema that will not parse, so `tospec schemas` and
+ * `tospec templates --schema <name>` say the same thing about the same file.
+ */
+function schemaParseFailureMessage(schemaPath, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return error instanceof SchemaValidationError
+        ? `Invalid schema at '${schemaPath}': ${detail}`
+        : `Failed to parse schema at '${schemaPath}': ${detail}`;
+}
 /**
  * The schema search path, **lowest precedence first** (package → user →
  * project). Every lookup and listing walks this one list, so adding a source
@@ -113,9 +92,9 @@ const schemaCache = new Map();
 function schemaSources(projectRoot) {
     return [
         { dir: getPackageSchemasDir(), source: 'package' },
-        // Both report 'user' — the legacy entry is one address for the same layer,
-        // and a 'legacy' value would widen the agent-facing JSON contract with
-        // something that stops existing once migration runs.
+        // Both report 'user': the legacy entry is another address for the same
+        // layer, and a 'legacy' value would widen the agent-facing JSON contract
+        // with something that stops existing once migration runs.
         { dir: getLegacySchemasDir(), source: 'user' },
         { dir: getUserSchemasDir(), source: 'user' },
         ...(projectRoot
@@ -132,51 +111,54 @@ function scanSchemaDir(dir) {
         .filter((entry) => isSchemaDir(dir, entry) && fs.existsSync(path.join(dir, entry.name, 'schema.yaml')))
         .map((entry) => entry.name);
 }
-export function getSchemaDir(name, projectRoot) {
+/**
+ * The directory holding `<name>/schema.yaml` and the layer it came from, or
+ * null when no layer has one. Project-local wins over the user override, which
+ * wins over the package built-in; without `projectRoot` only the last two are
+ * searched.
+ *
+ * The layer is resolved here rather than re-derived from the path by each
+ * caller: a directory is the *whole* schema, templates included, so "which layer
+ * won" is what explains a file the winning layer does not have.
+ */
+export function getSchemaDirWithSource(name, projectRoot) {
     // Highest precedence first: project overrides user overrides package.
-    for (const { dir } of schemaSources(projectRoot).reverse()) {
+    for (const { dir, source } of schemaSources(projectRoot).reverse()) {
         const candidate = path.join(dir, name);
         if (fs.existsSync(path.join(candidate, 'schema.yaml'))) {
-            return candidate;
+            return { dir: candidate, source };
         }
     }
     return null;
 }
+/** As `getSchemaDirWithSource`, for callers that only need the path. */
+export function getSchemaDir(name, projectRoot) {
+    return getSchemaDirWithSource(name, projectRoot)?.dir ?? null;
+}
 /**
- * Resolves a schema name to a SchemaYaml object.
- *
- * Resolution order (when projectRoot is provided):
- * 1. Project-local: <projectRoot>/tospec/schemas/<name>/schema.yaml
- * 2. User override: ${XDG_DATA_HOME}/tospec/schemas/<name>/schema.yaml
- * 3. Package built-in: <package>/schemas/<name>/schema.yaml
+ * The parsed schema, resolved through `getSchemaDir`'s precedence order.
  *
- * When projectRoot is not provided, only user override and package built-in are checked
- * (backward compatible behavior).
- *
- * @param name - Schema name (e.g., "sdd")
- * @param projectRoot - Optional project root directory for project-local schema resolution
- * @returns The resolved schema object
- * @throws Error if schema is not found in any location
+ * @throws SchemaLoadError when the file cannot be read or does not parse.
  */
 export function resolveSchema(name, projectRoot) {
-    // Normalize name (remove .yaml extension if provided)
     const normalizedName = name.replace(/\.ya?ml$/, '');
     const schemaDir = getSchemaDir(normalizedName, projectRoot);
     if (!schemaDir) {
-        const availableSchemas = listSchemas(projectRoot);
+        // Loadable, not merely present: a name whose schema.yaml does not parse is
+        // a choice that cannot work.
+        const availableSchemas = listLoadableSchemas(projectRoot);
         throw new Error(`Schema '${normalizedName}' not found. Available schemas: ${availableSchemas.join(', ')}`);
     }
     const schemaPath = path.join(schemaDir, 'schema.yaml');
-    // A single status/list run resolves the same schema once per change, and the
-    // dashboard re-resolves on every refresh; the yaml + Zod + cycle-check parse
-    // dominates that cost. One statSync decides whether it can be skipped.
+    // A status/list run resolves the same schema once per change and the dashboard
+    // re-resolves on every refresh, where the yaml + Zod + cycle-check parse
+    // dominates. One statSync decides whether it can be skipped.
     const stamp = fileStamp(schemaPath);
     const cached = stamp === null ? undefined : schemaCache.get(schemaPath);
     if (cached && cached.stamp === stamp) {
         // Cloned so a caller mutating its schema cannot corrupt later resolutions.
         return structuredClone(cached.schema);
     }
-    // Load and parse the schema
     let content;
     try {
         content = fs.readFileSync(schemaPath, 'utf-8');
@@ -193,19 +175,11 @@ export function resolveSchema(name, projectRoot) {
         return schema;
     }
     catch (err) {
-        if (err instanceof SchemaValidationError) {
-            throw new SchemaLoadError(`Invalid schema at '${schemaPath}': ${err.message}`, schemaPath, err);
-        }
-        const parseError = err instanceof Error ? err : new Error(String(err));
-        throw new SchemaLoadError(`Failed to parse schema at '${schemaPath}': ${parseError.message}`, schemaPath, parseError);
+        const cause = err instanceof Error ? err : new Error(String(err));
+        throw new SchemaLoadError(schemaParseFailureMessage(schemaPath, err), schemaPath, cause);
     }
 }
-/**
- * Lists all available schema names.
- * Combines project-local, user override, and package built-in schemas.
- *
- * @param projectRoot - Optional project root directory for project-local schema resolution
- */
+/** Every schema name on disk across all three layers. */
 export function listSchemas(projectRoot) {
     const schemas = new Set();
     for (const { dir } of schemaSources(projectRoot)) {
@@ -216,17 +190,33 @@ export function listSchemas(projectRoot) {
     return Array.from(schemas).sort();
 }
 /**
- * Lists all available schemas with their descriptions and artifact lists.
- * Useful for agent skills to present schema selection to users.
+ * Names of the schemas that actually load — what an "Available schemas:" list
+ * has to mean. `listSchemas` reports directory names, so a schema.yaml with a
+ * typo in it would be offered as a choice. Anything phrased as advice to the
+ * user belongs here.
+ */
+export function listLoadableSchemas(projectRoot) {
+    return listSchemasWithInfo(projectRoot)
+        .filter((schema) => schema.error === undefined)
+        .map((schema) => schema.name);
+}
+/**
+ * Every schema with its description and artifact list, for agent skills that
+ * present a schema choice.
  *
- * @param projectRoot - Optional project root directory for project-local schema resolution
+ * A schema that fails to parse is reported with `error` set, but only when no
+ * lower-precedence layer supplies a working schema of that name — a broken
+ * project override must not hide the package schema it shadows.
  */
 export function listSchemasWithInfo(projectRoot) {
     const schemas = [];
     const seenNames = new Set();
+    // Keyed by name so the highest-precedence failure is the one reported, and a
+    // later success removes it.
+    const broken = new Map();
     // Highest precedence first, so an overridden schema is skipped rather than
-    // replaced. A schema that fails to parse is not marked seen — the next
-    // source down still gets a chance to supply it.
+    // replaced. A schema that fails to parse is not marked seen — the next source
+    // down still gets a chance to supply it.
     for (const { dir, source } of schemaSources(projectRoot).reverse()) {
         for (const name of scanSchemaDir(dir)) {
             if (seenNames.has(name))
@@ -241,24 +231,33 @@ export function listSchemasWithInfo(projectRoot) {
                     path: path.join(dir, name),
                 });
                 seenNames.add(name);
+                broken.delete(name);
             }
-            catch {
-                // Skip invalid schemas
+            catch (error) {
+                if (broken.has(name))
+                    continue;
+                broken.set(name, {
+                    name,
+                    description: '',
+                    artifacts: [],
+                    source,
+                    path: path.join(dir, name),
+                    error: schemaParseFailureMessage(path.join(dir, name, 'schema.yaml'), error),
+                });
             }
         }
     }
-    return schemas.sort((a, b) => a.name.localeCompare(b.name));
+    return [...schemas, ...broken.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
 /**
  * Union of every artifact ID across every available schema.
  *
- * Config keys that are scoped per-artifact but stored globally (`rules:`) can
- * legitimately name an artifact from any schema, so they must be checked
- * against the union rather than whichever schema the current change uses.
+ * Config keys scoped per-artifact but stored globally (`rules:`) can
+ * legitimately name an artifact from any schema, so they are checked against the
+ * union rather than the current change's schema.
  *
- * Built on listSchemasWithInfo so it inherits that function's precedence
- * handling and its tolerance for a schema that fails to parse — one broken
- * custom schema must not turn every rules key into an unknown ID.
+ * Built on listSchemasWithInfo to inherit its tolerance for a schema that fails
+ * to parse: one broken custom schema must not turn every rules key unknown.
  */
 export function collectAllArtifactIds(projectRoot) {
     return new Set(listSchemasWithInfo(projectRoot).flatMap((schema) => schema.artifacts));