@fission-ai/openspec 1.6.0 → 1.7.0

package/dist/core/validation/validator.d.ts

@@ -18,13 +18,7 @@ export declare class Validator {
      * - No duplicates within sections; no cross-section conflicts per spec
      */
     validateChangeDeltaSpecs(changeDir: string): Promise<ValidationReport>;
-    /**
-     * Recursively collect every delta `spec.md` under a change's specs directory,
-     * so both the one-level (specs/<capability>/spec.md) and nested multi-area
-     * (specs/<area>/<capability>/spec.md) layouts are discovered (#1182b).
-     * Returns absolute paths, sorted for deterministic issue ordering.
-     */
-    private findDeltaSpecFiles;
+    private formatInvalidMarkerMessage;
     private convertZodErrors;
     private applySpecRules;
     private applyChangeRules;

package/dist/core/validation/validator.js

@@ -4,10 +4,12 @@ import { SpecSchema, ChangeSchema } from '../schemas/index.js';
 import { MarkdownParser } from '../parsers/markdown-parser.js';
 import { ChangeParser } from '../parsers/change-parser.js';
 import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, VALIDATION_MESSAGES } from './constants.js';
-import { parseDeltaSpec, normalizeRequirementName, extractRequirementsSection } from '../parsers/requirement-blocks.js';
+import { parseDeltaSpec, foldRequirementName, normalizeRequirementName, extractRequirementsSection } from '../parsers/requirement-blocks.js';
 import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust as containsShallOrMustShared, countScenarios as countScenariosShared, } from '../parsers/requirement-text.js';
 import { findMainSpecStructureIssues } from '../parsers/spec-structure.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
+import { discoverSpecFiles, hasAnyFileUnder } from '../../utils/spec-discovery.js';
+import { METADATA_FILENAME, readSkipSpecsMarker } from '../../utils/change-metadata.js';
 export class Validator {
     strictMode;
     constructor(strictMode = false) {
@@ -67,8 +69,20 @@ export class Validator {
             const parser = new ChangeParser(content, changeDir);
             const change = await parser.parseChangeWithDeltas(changeName);
             const result = ChangeSchema.safeParse(change);
+            const marker = readSkipSpecsMarker(changeDir);
+            if (marker.invalidReason) {
+                issues.push({ level: 'ERROR', path: METADATA_FILENAME, message: this.formatInvalidMarkerMessage(marker.invalidReason) });
+            }
             if (!result.success) {
-                issues.push(...this.convertZodErrors(result.error));
+                let zodIssues = this.convertZodErrors(result.error);
+                // Only the no-deltas error is marker-aware here: the marker+files
+                // conflict is validateChangeDeltaSpecs's job, and every caller of
+                // this proposal-level pass (archive's non-blocking warnings) pairs
+                // it with that gate.
+                if (marker.declared) {
+                    zodIssues = zodIssues.filter(issue => !issue.message.startsWith(VALIDATION_MESSAGES.CHANGE_NO_DELTAS));
+                }
+                issues.push(...zodIssues);
             }
             issues.push(...this.applyChangeRules(change, content));
         }
@@ -96,14 +110,30 @@ export class Validator {
         const issues = [];
         const specsDir = path.join(changeDir, 'specs');
         let totalDeltas = 0;
+        let hasRootLevelSpec = false;
         const missingHeaderSpecs = [];
         const emptySectionSpecs = [];
         try {
-            // Discover delta specs at any depth so the nested multi-area layout
-            // (specs/<area>/<capability>/spec.md) is validated, not just the
-            // one-level specs/<capability>/spec.md layout (#1182b). The spec-driven
-            // specs glob is specs/**/*.md; delta files are always named spec.md.
-            const specFiles = await this.findDeltaSpecFiles(specsDir);
+            // Discover delta specs through the same helper the change parser, show,
+            // apply, and archive use, so validate never accepts a layout the merge
+            // path silently skips (#1385). It finds spec.md at any depth, covering
+            // both specs/<capability>/spec.md and the nested multi-area
+            // specs/<area>/<capability>/spec.md layout (#1182b).
+            const specFiles = (await discoverSpecFiles(specsDir)).map(spec => spec.specFile);
+            // A spec.md directly at the specs/ root has no capability folder, so the
+            // merge path drops it: without this error the change validates clean and
+            // archives while its requirements never reach openspec/specs/ (#1385).
+            // Only a regular file counts — a *directory* named spec.md is a capability
+            // folder like any other, and discoverSpecFiles reads it normally.
+            const rootSpecStat = await fs.stat(path.join(specsDir, 'spec.md')).catch(() => null);
+            hasRootLevelSpec = rootSpecStat?.isFile() === true;
+            if (hasRootLevelSpec) {
+                issues.push({
+                    level: 'ERROR',
+                    path: 'spec.md',
+                    message: 'Delta spec found at specs/spec.md. Delta specs must live in a capability folder (e.g. specs/<capability>/spec.md) — a file at the specs/ root is ignored when the change is applied or archived.',
+                });
+            }
             for (const specFile of specFiles) {
                 let content;
                 try {
@@ -261,11 +291,30 @@ export class Validator {
                     if (addedNames.has(toKey)) {
                         issues.push({ level: 'ERROR', path: entryPath, message: `RENAMED TO collides with ADDED for "${to}"` });
                     }
+                    // Folded comparison: a case/whitespace variant of the FROM header
+                    // in REMOVED is the same contradiction, not a different name.
+                    const removedFoldMatch = [...removedNames].find((r) => foldRequirementName(r) === foldRequirementName(fromKey));
+                    if (removedFoldMatch !== undefined) {
+                        issues.push({
+                            level: 'ERROR',
+                            path: entryPath,
+                            message: `Requirement present in both RENAMED and REMOVED: "${from}"` +
+                                (removedFoldMatch === fromKey ? '' : ` (REMOVED spells it "${removedFoldMatch}")`),
+                        });
+                    }
                 }
             }
         }
-        catch {
-            // If no specs dir, treat as no deltas
+        catch (error) {
+            // A missing specs dir (or a stray `specs` file) means no deltas;
+            // anything else (EACCES, EIO) must stay loud — discoverSpecFiles
+            // documents that silently dropping an unreadable capability recreates
+            // the data-loss class it prevents, and archive lets the same error
+            // propagate.
+            const code = error?.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+                throw error;
+            }
         }
         for (const { path: specPath, sections } of emptySectionSpecs) {
             issues.push({
@@ -281,39 +330,46 @@ export class Validator {
                 message: 'No delta sections found. Add headers such as "## ADDED Requirements" or move non-delta notes outside specs/.',
             });
         }
-        if (totalDeltas === 0) {
-            issues.push({ level: 'ERROR', path: 'file', message: this.enrichTopLevelError('change', VALIDATION_MESSAGES.CHANGE_NO_DELTAS) });
+        const marker = readSkipSpecsMarker(changeDir);
+        if (marker.invalidReason) {
+            issues.push({ level: 'ERROR', path: METADATA_FILENAME, message: this.formatInvalidMarkerMessage(marker.invalidReason) });
         }
-        return this.createReport(issues);
-    }
-    /**
-     * Recursively collect every delta `spec.md` under a change's specs directory,
-     * so both the one-level (specs/<capability>/spec.md) and nested multi-area
-     * (specs/<area>/<capability>/spec.md) layouts are discovered (#1182b).
-     * Returns absolute paths, sorted for deterministic issue ordering.
-     */
-    async findDeltaSpecFiles(specsDir) {
-        const results = [];
-        const walk = async (dir) => {
-            let entries;
+        // ANY file under specs/ contradicts the marker - not just parsed deltas.
+        // Headerless or stray files would be silently dropped at archive time (and
+        // some still satisfy the artifact graph's specs/**  glob) while the change
+        // claims to have nothing, so they must surface as an explicit conflict.
+        // Probed only when the marker is declared, and unreadable specs/ (a stray
+        // `specs` file, permission errors) fails closed as a conflict: the marker
+        // claims nothing is there, and validate must not crash where the
+        // historical path degraded to "no deltas".
+        const skipSpecs = marker.declared;
+        let specsDirHasFiles = false;
+        if (skipSpecs) {
             try {
-                entries = await fs.readdir(dir, { withFileTypes: true });
+                specsDirHasFiles = await hasAnyFileUnder(specsDir);
             }
             catch {
-                return;
+                specsDirHasFiles = true;
             }
-            for (const entry of entries) {
-                const full = path.join(dir, entry.name);
-                if (entry.isDirectory()) {
-                    await walk(full);
-                }
-                else if (entry.isFile() && entry.name === 'spec.md') {
-                    results.push(full);
-                }
+        }
+        if (skipSpecs && specsDirHasFiles) {
+            issues.push({ level: 'ERROR', path: 'file', message: VALIDATION_MESSAGES.CHANGE_SKIP_SPECS_CONFLICT });
+        }
+        // The root-level error already names the file and the fix; adding "No
+        // deltas found" on top would contradict it, since the deltas are sitting in
+        // the file just reported.
+        if (totalDeltas === 0 && !hasRootLevelSpec) {
+            if (skipSpecs && !specsDirHasFiles) {
+                issues.push({ level: 'INFO', path: 'file', message: VALIDATION_MESSAGES.CHANGE_SKIP_SPECS_ACCEPTED });
             }
-        };
-        await walk(specsDir);
-        return results.sort();
+            else if (!skipSpecs) {
+                issues.push({ level: 'ERROR', path: 'file', message: this.enrichTopLevelError('change', VALIDATION_MESSAGES.CHANGE_NO_DELTAS) });
+            }
+        }
+        return this.createReport(issues);
+    }
+    formatInvalidMarkerMessage(invalidReason) {
+        return `${VALIDATION_MESSAGES.CHANGE_SKIP_SPECS_INVALID_METADATA} (${invalidReason})`;
     }
     convertZodErrors(error) {
         return error.issues.map(err => {

package/dist/core/version-check.d.ts

@@ -0,0 +1,152 @@
+/**
+ * The registry to ask: only the environment variable npm exports (under
+ * `npm run`, or an explicit export). Deliberately not a `registry=` line from
+ * any .npmrc — letting file contents choose the destination of an outbound
+ * request is a flow worth avoiding for a convenience this small, and a project
+ * file would travel with a cloned repository. Anyone on a private mirror can
+ * export `npm_config_registry`, or turn the check off entirely.
+ */
+export declare function registryUrl(): string;
+/**
+ * Compares two semver-ish versions. Returns 1 when a > b, -1 when a < b, 0
+ * otherwise. Prereleases sort below their release (1.7.0-beta.1 < 1.7.0).
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Returns the published version when the installed CLI is behind it, otherwise
+ * null. Never throws and never blocks for longer than the request timeout.
+ */
+export declare function getAvailableCliUpdate(): Promise<string | null>;
+/**
+ * Directory the running CLI was loaded from, or null when it cannot be
+ * resolved. Shown in the upgrade hint so anyone who upgraded but still runs an
+ * old binary — a stale pnpm/volta/npx shim, or two installs on PATH — can see
+ * which copy is actually answering.
+ */
+export declare function getInstallDir(): string | null;
+/**
+ * True when the running CLI resolves from a `node_modules` belonging to the
+ * project being updated or any ancestor of it — the hoisted-root layout npm and
+ * pnpm workspaces produce. Anchored on the target path rather than the working
+ * directory, since `openspec update <path>` and running from a sub-package are
+ * both normal. Never throws: process.cwd() fails when the directory has been
+ * deleted, and a wrong upgrade hint must not take down a successful update.
+ */
+export declare function isProjectLocalInstall(installDir: string | null, projectPath?: string): boolean;
+/**
+ * True for the throwaway caches npx/pnpm dlx/bunx unpack into. Telling those
+ * users to install globally would create the second copy on PATH they were
+ * deliberately avoiding.
+ */
+export declare function isEphemeralRunnerInstall(installDir: string | null): boolean;
+/**
+ * Directories npm installs global packages into. Derived from the running node
+ * rather than by shelling out to `npm prefix -g`, which would cost more than
+ * the version check itself. Only a hint: `process.execPath` is realpath'd, so
+ * on Homebrew it lands in the Cellar rather than the brew prefix — which is
+ * why the install's own layout is the primary signal below.
+ */
+export declare function npmGlobalRoots(): string[];
+/**
+ * The prefix of an npm global install, read from the install's own shape:
+ * `<prefix>/lib/node_modules/<pkg>` on POSIX, `<prefix>/node_modules/<pkg>` on
+ * Windows. Self-describing, so it holds for Homebrew, nvm, Debian and anywhere
+ * else npm's prefix is not derivable from the node binary. Null when the
+ * layout does not match.
+ */
+export declare function npmPrefixFromInstallDir(installDir: string | null): string | null;
+/**
+ * True only when npm itself owns this copy. Everything else — a pnpm, bun,
+ * yarn or volta global — would be made worse by `npm install -g`, which adds a
+ * second copy that may not even be the one on PATH.
+ */
+export declare function isNpmGlobalInstall(installDir: string | null, roots?: string[]): boolean;
+/**
+ * True when the CLI is running from a clone rather than an install. Upgrade
+ * advice is meaningless there: the version is whatever the branch says.
+ */
+export declare function isSourceCheckout(installDir: string | null): boolean;
+export type PackageManager = 'npm' | 'pnpm' | 'bun' | 'yarn' | 'volta';
+/**
+ * The package manager that owns this copy, so the printed command is one the
+ * user's setup will actually honor.
+ */
+export declare function detectPackageManager(installDir: string | null): PackageManager;
+/**
+ * Builds the hint, with the upgrade command chosen for how this copy of the CLI
+ * was installed. Pure so every branch is assertable.
+ */
+export declare function buildCliUpdateLines(latestVersion: string, installDir: string | null, projectPath: string, options?: {
+    withCommand?: boolean;
+}): string[];
+/**
+ * The upgrade command for however this copy was installed, plus the reminder
+ * that instruction files come from the CLI and so need a second pass.
+ */
+export declare function buildUpgradeCommandLines(installDir: string | null, projectPath: string): string[];
+/**
+ * Whether we can run the upgrade for the user instead of only printing it.
+ *
+ * Only an npm-owned global install qualifies, because `npm install -g` is the
+ * only command we run: a pnpm/bun/yarn/volta global would get a second copy
+ * that may not be the one on PATH, a project dependency belongs to that
+ * project's package manager, an npx/dlx cache has nothing to upgrade, and a
+ * source checkout is not an install at all.
+ */
+export declare function canSelfUpgrade(installDir: string | null, projectPath: string): boolean;
+/**
+ * Whether to offer the upgrade rather than just print the command. Kept here,
+ * as a pure function of the environment, because the interesting mistakes live
+ * in this decision: offering where `npm install -g` cannot help, or asking a
+ * question no one can answer.
+ */
+export declare function shouldOfferUpgrade(params: {
+    installDir: string | null;
+    projectPath: string;
+    interactive: boolean;
+    stdoutIsTty: boolean;
+}): boolean;
+/**
+ * The `openspec` npm installs alongside its global package, so the upgrade can
+ * be handed to the copy npm just wrote rather than to whatever PATH resolves.
+ * Null when it cannot be found, in which case PATH is the only option left.
+ */
+export declare function upgradedBinPath(roots?: string[], installDir?: string | null): string | null;
+/**
+ * Asks a CLI binary its version. Used to confirm an upgrade actually landed:
+ * `npm install -g` exits 0 even when it installed nothing, so its exit code
+ * alone cannot justify telling the user they are on a new version.
+ */
+export declare function readCliVersion(binPath: string): Promise<string | null>;
+export type UpgradeOutcome = 'upgraded' | 'declined' | 'failed' | 'cancelled' | 'not-on-path';
+/**
+ * Offers to run the upgrade and reports what actually happened. The version is
+ * read back from the installed binary rather than assumed, so "upgraded" is a
+ * fact and a PATH that still answers with the old copy is caught here instead
+ * of silently doing nothing.
+ */
+export declare function offerCliUpgrade(latestVersion: string): Promise<UpgradeOutcome>;
+/**
+ * Runs `openspec update` again with the CLI that was just installed — this
+ * process is still the old code, so it cannot write the new workflows itself.
+ * Resolves the exit code to pass along; when no `openspec` is on PATH the
+ * upgrade still landed but nothing was regenerated, so it says so and
+ * resolves 0 rather than reporting a failure the upgrade did not have.
+ */
+export declare function rerunUpdateWithUpgradedCli(projectPath: string, options?: {
+    force?: boolean;
+    binPath?: string;
+}): Promise<number>;
+/**
+ * Prints the upgrade hint. Instruction files are generated by the installed
+ * CLI, so "up to date" only ever means "matches this CLI" — without this note
+ * a stale install looks like a successful update.
+ */
+export declare function displayCliUpdateNote(latestVersion: string, projectPath?: string, options?: {
+    withCommand?: boolean;
+}): void;
+/**
+ * Prints just the manual command, for when the offer was declined or failed.
+ */
+export declare function displayUpgradeCommand(projectPath?: string): void;
+//# sourceMappingURL=version-check.d.ts.map