@matteeh/osq 0.1.0 → 0.2.1

package/dist/core/{hasher.js → spec/hasher.js}

@@ -1,20 +1,44 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+/**
+ * Directory or metadata names excluded from every authored-content view of a
+ * change folder, at any depth. These mirror the runtime state the engine owns
+ * rather than the author's specification.
+ */
+const CHANGE_FOLDER_EXCLUDED_SEGMENTS = new Set(['.run', '.git', '.DS_Store']);
+/**
+ * Transient files owned by the engine at a change folder's root only. A nested
+ * file with the same name is authored content and stays covered.
+ */
+const CHANGE_FOLDER_TRANSIENT_FILES = new Set(['plan-prompt.md']);
+/**
+ * The single root-relative exclusion predicate shared by hashing and linting.
+ * `relPath` is a project-folder-relative POSIX path such as `.run/done/1` or
+ * `plan-prompt.md`. Nested runtime directories stay excluded, but a transient
+ * file is only transient at the change folder root.
+ */
+export function isExcludedChangePath(relPath) {
+    const normalized = relPath.replace(/\\/g, '/');
+    if (CHANGE_FOLDER_TRANSIENT_FILES.has(normalized)) {
+        return true;
+    }
+    return normalized.split('/').some((segment) => CHANGE_FOLDER_EXCLUDED_SEGMENTS.has(segment));
+}
 async function collectFiles(dir, baseDir) {
     const entries = await fs.readdir(dir, { withFileTypes: true });
     const files = [];
     for (const entry of entries) {
-        if (entry.name === '.run' || entry.name === '.git' || entry.name === '.DS_Store') {
+        const fullPath = path.join(dir, entry.name);
+        const relPath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
+        if (isExcludedChangePath(relPath)) {
             continue;
         }
-        const fullPath = path.join(dir, entry.name);
         if (entry.isDirectory()) {
             const nested = await collectFiles(fullPath, baseDir);
             files.push(...nested);
         }
         else if (entry.isFile()) {
-            const relPath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
             files.push(relPath);
         }
     }

package/dist/core/spec/hasher.js.map

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

package/dist/core/spec/linter.d.ts

@@ -0,0 +1,79 @@
+import type { OsqConfig } from '../foundation/config.js';
+import { OPENSPEC_EXPECTED_VERSION } from './openspec-version.js';
+export { OPENSPEC_EXPECTED_VERSION };
+/** Prefix applied to every finding surfaced by the OpenSpec validator. */
+export declare const OPENSPEC_ERROR_PREFIX = "openspec:";
+export interface LintLogger {
+    info(msg: string): void;
+    verbose(msg: string): void;
+    warn(msg: string): void;
+}
+/**
+ * The outcome of analyzing one verify command. Every field is derived without
+ * executing or shell-expanding the command.
+ */
+export interface VerifyCommandAnalysis {
+    /** The command is the template sentinel or a normalized equivalent. */
+    readonly placeholder: boolean;
+    /** The recognized package script name, when the command invokes one. */
+    readonly packageScript: string | null;
+    /** The recognized package script name that the root manifest lacks. */
+    readonly missingScript: string | null;
+    /** No existing repository path and no recognized package script was named. */
+    readonly unresolved: boolean;
+}
+/**
+ * Analyze one verify command read-only: detect the template sentinel, resolve a
+ * recognized package script against the root manifest, or fall back to an
+ * unresolved-target warning when no existing path or script is named.
+ */
+export declare function analyzeVerifyCommand(projectRoot: string, command: string, packageScripts: ReadonlySet<string>): Promise<VerifyCommandAnalysis>;
+export interface LintResult {
+    readonly valid: boolean;
+    readonly errors: string[];
+    readonly warnings: string[];
+}
+export interface LintOptions {
+    readonly logger?: LintLogger;
+}
+export interface OpenSpecFindings {
+    readonly errors: string[];
+    readonly warnings: string[];
+}
+export interface OpenSpecValidationOutcome extends OpenSpecFindings {
+    readonly ran: boolean;
+    readonly bin: string | null;
+    readonly version: string | null;
+}
+/**
+ * Resolves the project-local OpenSpec binary. Only a binary inside the
+ * project's own `node_modules/.bin` (or an explicitly configured absolute
+ * path) is used; missing installs resolve to `null` so linting degrades
+ * gracefully rather than failing on projects without OpenSpec.
+ */
+export declare function resolveOpenSpecBin(projectRoot: string, config: OsqConfig): Promise<string | null>;
+/** Reads the resolved `@fission-ai/openspec` version from the local install. */
+export declare function resolveOpenSpecVersion(projectRoot: string): Promise<string | null>;
+/**
+ * Tolerantly extracts validation findings from `openspec validate --json`.
+ * Accepts a top-level array or an object exposing `issues`/`errors`/`warnings`
+ * (or similar) and classifies each finding by its error/warning severity.
+ */
+export declare function parseOpenSpecFindings(output: string): OpenSpecFindings;
+/**
+ * Runs the local OpenSpec validator for changes and specs. Validation failures
+ * are returned prefixed with `openspec:`. A missing binary or a version outside
+ * the declared peer range is an error that cites ADR 004 and the install
+ * command; a version inside the range that differs from the pin warns and cites
+ * ADR 005. Linting fails closed rather than silently degrading.
+ */
+export declare function validateWithOpenSpec(projectRoot: string, config: OsqConfig, options?: LintOptions): Promise<OpenSpecValidationOutcome>;
+/**
+ * Verifies that every delta operation targeting a requirement resolves against
+ * the living base spec at `openspec/specs/<capability>/spec.md`. Applying the
+ * delta through the deterministic merge engine reports unmatched MODIFIED,
+ * REMOVED, or RENAMED targets; ADDED-only deltas may create a new capability.
+ */
+export declare function verifyDeltaTargets(projectRoot: string, folderPath: string, config: OsqConfig): Promise<string[]>;
+export declare function lintChangeFolder(projectRoot: string, folderPath: string, config: OsqConfig, options?: LintOptions): Promise<LintResult>;
+//# sourceMappingURL=linter.d.ts.map

package/dist/core/spec/linter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linter.d.ts","sourceRoot":"","sources":["../../../src/core/spec/linter.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAMzD,OAAO,EACL,yBAAyB,EAI1B,MAAM,uBAAuB,CAAC;AAqB/B,OAAO,EAAE,yBAAyB,EAAE,CAAC;AAMrC,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,cAAc,CAAC;AAEjD,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AA8GD;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,uEAAuE;IACvE,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AA4CD;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,GAClC,OAAO,CAAC,qBAAqB,CAAC,CAuBhC;AAoFD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,yBAA0B,SAAQ,gBAAgB;IACjE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AA8BD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASxB;AAED,gFAAgF;AAChF,wBAAsB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgBxF;AAiDD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CA2DtE;AAuCD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,EACjB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,yBAAyB,CAAC,CAkEpC;AA4DD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,MAAM,EAAE,CAAC,CAoDnB;AAsGD,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,SAAS,EACjB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC,CAyNrB"}