@seanmars/tospec 0.19.0-beta.0 → 0.19.0-beta.13

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

@@ -2,15 +2,71 @@ 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('[');
 }
 /**
- * Resolves an artifact's output path(s) to concrete files that currently exist.
- * Returns absolute file paths. Glob matches are sorted for deterministic output.
+ * A pattern whose wildcard occupies exactly one whole path segment, with every
+ * other segment literal — `specs/*` or `specs/<*>/spec.md`.
+ *
+ * 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.
+ *
+ * `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('/');
+    let wildcardIndex = -1;
+    for (let i = 0; i < segments.length; i++) {
+        if (!isGlobPattern(segments[i]))
+            continue;
+        // A second wildcard segment, or a wildcard sharing a segment with literal
+        // text (`spec-*.md`), is out of scope.
+        if (wildcardIndex !== -1 || segments[i] !== '*')
+            return null;
+        wildcardIndex = i;
+    }
+    if (wildcardIndex === -1)
+        return null;
+    return { prefix: segments.slice(0, wildcardIndex), suffix: segments.slice(wildcardIndex + 1) };
+}
+/** 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 };
+}
+/**
+ * Absolute paths of the files an artifact's `generates` currently resolves to.
+ * Sorted, for deterministic output.
  */
 export function resolveArtifactOutputs(changeDir, generates) {
     if (!isGlobPattern(generates)) {
@@ -24,15 +80,97 @@ export function resolveArtifactOutputs(changeDir, generates) {
             return [];
         }
     }
+    const single = splitSingleWildcard(generates);
+    if (single) {
+        const baseDir = path.join(changeDir, ...single.prefix);
+        let entries;
+        try {
+            entries = fs.readdirSync(baseDir);
+        }
+        catch {
+            return [];
+        }
+        const matches = [];
+        for (const entry of entries) {
+            // fast-glob's `*` does not match a leading dot; the fast path must not
+            // start counting `.hidden/spec.md` as an output.
+            if (entry.startsWith('.'))
+                continue;
+            const candidate = path.join(baseDir, entry, ...single.suffix);
+            try {
+                // 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() && hasExactSuffixSpelling(path.join(baseDir, entry), single.suffix)) {
+                    matches.push(FileSystemUtils.canonicalizeExistingPath(candidate));
+                }
+            }
+            catch {
+                // Nothing at that path under this entry.
+            }
+        }
+        return finalizeMatches(matches);
+    }
     const normalizedPattern = FileSystemUtils.toPosixPath(generates);
     const matches = fg
-        .sync(normalizedPattern, { cwd: changeDir, onlyFiles: true, absolute: true })
+        .sync(normalizedPattern, globFallbackOptions(changeDir))
         .map((match) => FileSystemUtils.canonicalizeExistingPath(path.normalize(match)));
-    return Array.from(new Set(matches)).sort();
+    return finalizeMatches(matches);
 }
 /**
- * Checks if an artifact has at least one resolved output file.
+ * 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, 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. Any behaviour added to one
+ * belongs in that list.
  */
+export async function resolveArtifactOutputsAsync(changeDir, generates) {
+    if (!isGlobPattern(generates)) {
+        const fullPath = path.join(changeDir, generates);
+        try {
+            return (await fs.promises.stat(fullPath)).isFile()
+                ? [FileSystemUtils.canonicalizeExistingPath(fullPath)]
+                : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    const single = splitSingleWildcard(generates);
+    if (single) {
+        const baseDir = path.join(changeDir, ...single.prefix);
+        let entries;
+        try {
+            entries = await fs.promises.readdir(baseDir);
+        }
+        catch {
+            return [];
+        }
+        const matches = await Promise.all(entries.map(async (entry) => {
+            if (entry.startsWith('.'))
+                return null;
+            const candidate = path.join(baseDir, entry, ...single.suffix);
+            try {
+                return (await fs.promises.stat(candidate)).isFile() &&
+                    (await hasExactSuffixSpellingAsync(path.join(baseDir, entry), single.suffix))
+                    ? FileSystemUtils.canonicalizeExistingPath(candidate)
+                    : null;
+            }
+            catch {
+                return null;
+            }
+        }));
+        return finalizeMatches(matches.filter((m) => m !== null));
+    }
+    const normalizedPattern = FileSystemUtils.toPosixPath(generates);
+    const matches = (await fg(normalizedPattern, globFallbackOptions(changeDir))).map((match) => FileSystemUtils.canonicalizeExistingPath(path.normalize(match)));
+    return finalizeMatches(matches);
+}
 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":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,MAAM,WAAW,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE7D;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AACjF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAiB,EAAE,SAAiB;IACzE,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QACjD,IAAI,CAAC;YACH,OAAO,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE;gBACnC,CAAC,CAAC,CAAC,eAAe,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAAC;gBACtD,CAAC,CAAC,EAAE,CAAC;QACT,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAED,MAAM,iBAAiB,GAAG,eAAe,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IACjE,MAAM,OAAO,GAAG,EAAE;SACf,IAAI,CAAC,iBAAiB,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;SAC5E,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,wBAAwB,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEnF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB,EAAE,SAAiB;IACvE,OAAO,sBAAsB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AACjE,CAAC"}
+{"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;gBAF7B,OAAO,EAAE,MAAM,EACC,UAAU,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,KAAK,YAAA;CAKhC;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"}