@seanmars/tospec 0.19.0-beta.8 → 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,80 +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
- *
- * When projectRoot is not provided, only user override and package built-in are checked
- * (backward compatible behavior).
+ * 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.
  *
- * @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[];
 /**
  * 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 was
- * offered as a choice and then produced an unusable change (round 4 report 5).
- * Anything phrased as advice to the user belongs on this list; enumeration of
- * what is on disk stays on `listSchemas`.
+ * 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[];
-/**
- * Schema info with metadata (name, description, artifacts).
- */
 export interface SchemaInfo {
     name: string;
     description: string;
@@ -100,44 +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, when it could not be. Present only on
-     * a broken entry, which also has an empty `artifacts` list.
-     *
-     * Round 4 report 5: dropping these silently meant a schema author who typo'd
-     * their YAML saw a list that simply did not contain their schema, with no
-     * hint why — while `new change --schema <typo>` still advertised the name as
-     * available and then created an unusable change from it. Carrying the failure
-     * in place is the same rule `list` follows for an unreadable change
-     * (tospec/decisions/20260917_234821-batch-commands-degrade-per-item.md).
+     * 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.
  *
  * 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.
- *
- * @param projectRoot - Optional project root directory for project-local schema resolution
  */
 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,CA4D5E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAIlE;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;IACb;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE,CA+CtE;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"}