specgov 0.1.0

package/dist/manifest.js

@@ -0,0 +1,232 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parse } from "yaml";
+import { SpecGovError } from "./errors.js";
+export const DEFAULT_CONFIG_PATH = ".specgov.yml";
+const DEFAULT_RULES = {
+    require_spec_impact_for_code_changes: true,
+    require_lifecycle_status: false,
+    require_owner_for_active_specs: false,
+    stale_after_days: 180,
+};
+export const DEFAULT_CONFIG_TEMPLATE = `version: 1
+mode: advisory
+
+artifacts:
+  - path: "docs/**/*.md"
+    kind: documentation
+    owner: docs
+  - path: "adr/**/*.md"
+    kind: decision
+    owner: architecture
+  - path: ".specs/**/*.md"
+    kind: specification
+    owner: engineering
+
+mappings:
+  - code: "src/**"
+    specs:
+      - "docs/**"
+      - "adr/**"
+      - ".specs/**"
+
+rules:
+  require_spec_impact_for_code_changes: true
+  require_lifecycle_status: false
+  require_owner_for_active_specs: false
+  stale_after_days: 180
+
+ignore:
+  - "node_modules/**"
+  - "dist/**"
+  - ".git/**"
+`;
+export async function loadConfig(cwd, configPath = DEFAULT_CONFIG_PATH) {
+    const absolutePath = path.resolve(cwd, configPath);
+    let text;
+    try {
+        text = await fs.readFile(absolutePath, "utf8");
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === "ENOENT") {
+            throw new SpecGovError(`SpecGov manifest not found at ${configPath}. Run "specgov init" first.`);
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = parse(text);
+    }
+    catch (error) {
+        throw new SpecGovError(`Invalid YAML in ${configPath}: ${error.message}`);
+    }
+    return normalizeConfig(parsed, configPath);
+}
+export async function writeDefaultConfig(cwd, configPath = DEFAULT_CONFIG_PATH, force = false) {
+    const absolutePath = path.resolve(cwd, configPath);
+    if (!force) {
+        try {
+            await fs.access(absolutePath);
+            throw new SpecGovError(`SpecGov manifest already exists at ${configPath}. Use --force to overwrite.`);
+        }
+        catch (error) {
+            if (error instanceof SpecGovError) {
+                throw error;
+            }
+            const nodeError = error;
+            if (nodeError.code !== "ENOENT") {
+                throw error;
+            }
+        }
+    }
+    await fs.writeFile(absolutePath, DEFAULT_CONFIG_TEMPLATE, "utf8");
+}
+export function normalizeConfig(input, source = DEFAULT_CONFIG_PATH) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        throw new SpecGovError(`Invalid ${source}: expected a YAML object.`);
+    }
+    const raw = input;
+    return {
+        version: normalizeVersion(raw.version),
+        mode: normalizeMode(raw.mode),
+        artifacts: normalizeArtifacts(raw.artifacts),
+        mappings: normalizeMappings(raw.mappings),
+        rules: normalizeRules(raw.rules),
+        ignore: normalizeStringArray(raw.ignore, "ignore", true),
+    };
+}
+function normalizeVersion(value) {
+    if (value === undefined) {
+        return 1;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+        throw new SpecGovError("Invalid manifest: version must be a positive integer.");
+    }
+    return value;
+}
+function normalizeMode(value) {
+    if (value === undefined) {
+        return "advisory";
+    }
+    if (value === "advisory" || value === "strict") {
+        return value;
+    }
+    throw new SpecGovError('Invalid manifest: mode must be "advisory" or "strict".');
+}
+function normalizeRules(value) {
+    if (value === undefined) {
+        return { ...DEFAULT_RULES };
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new SpecGovError("Invalid manifest: rules must be an object.");
+    }
+    const raw = value;
+    return {
+        require_spec_impact_for_code_changes: boolOrDefault(raw.require_spec_impact_for_code_changes, DEFAULT_RULES.require_spec_impact_for_code_changes, "rules.require_spec_impact_for_code_changes"),
+        require_lifecycle_status: boolOrDefault(raw.require_lifecycle_status, DEFAULT_RULES.require_lifecycle_status, "rules.require_lifecycle_status"),
+        require_owner_for_active_specs: boolOrDefault(raw.require_owner_for_active_specs, DEFAULT_RULES.require_owner_for_active_specs, "rules.require_owner_for_active_specs"),
+        stale_after_days: numberOrDefault(raw.stale_after_days, DEFAULT_RULES.stale_after_days, "rules.stale_after_days"),
+    };
+}
+function normalizeArtifacts(value) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new SpecGovError("Invalid manifest: artifacts must be a list.");
+    }
+    return value.map((item, index) => {
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            throw new SpecGovError(`Invalid manifest: artifacts[${index}] must be an object.`);
+        }
+        const raw = item;
+        const artifact = {
+            path: normalizeStringOrArray(raw.path, `artifacts[${index}].path`),
+            kind: stringOrThrow(raw.kind, `artifacts[${index}].kind`),
+        };
+        if (raw.owner !== undefined) {
+            artifact.owner = stringOrThrow(raw.owner, `artifacts[${index}].owner`);
+        }
+        if (raw.status !== undefined) {
+            artifact.status = normalizeStatus(raw.status, `artifacts[${index}].status`);
+        }
+        return artifact;
+    });
+}
+function normalizeMappings(value) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new SpecGovError("Invalid manifest: mappings must be a list.");
+    }
+    return value.map((item, index) => {
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            throw new SpecGovError(`Invalid manifest: mappings[${index}] must be an object.`);
+        }
+        const raw = item;
+        const mapping = {
+            code: normalizeStringOrArray(raw.code, `mappings[${index}].code`),
+            specs: normalizeStringOrArray(raw.specs, `mappings[${index}].specs`),
+        };
+        if (raw.description !== undefined) {
+            mapping.description = stringOrThrow(raw.description, `mappings[${index}].description`);
+        }
+        return mapping;
+    });
+}
+function normalizeStatus(value, field) {
+    if (value === "draft" ||
+        value === "active" ||
+        value === "superseded" ||
+        value === "deprecated" ||
+        value === "archived") {
+        return value;
+    }
+    throw new SpecGovError(`Invalid manifest: ${field} has unsupported lifecycle status.`);
+}
+function normalizeStringOrArray(value, field) {
+    if (typeof value === "string" && value.trim()) {
+        return value;
+    }
+    if (Array.isArray(value) &&
+        value.every((entry) => typeof entry === "string" && entry.trim())) {
+        return value;
+    }
+    throw new SpecGovError(`Invalid manifest: ${field} must be a string or list of strings.`);
+}
+function normalizeStringArray(value, field, withDefaults = false) {
+    if (value === undefined) {
+        return withDefaults ? ["node_modules/**", "dist/**", ".git/**"] : [];
+    }
+    if (Array.isArray(value) &&
+        value.every((entry) => typeof entry === "string" && entry.trim())) {
+        return value;
+    }
+    throw new SpecGovError(`Invalid manifest: ${field} must be a list of strings.`);
+}
+function stringOrThrow(value, field) {
+    if (typeof value === "string" && value.trim()) {
+        return value;
+    }
+    throw new SpecGovError(`Invalid manifest: ${field} must be a non-empty string.`);
+}
+function boolOrDefault(value, defaultValue, field) {
+    if (value === undefined) {
+        return defaultValue;
+    }
+    if (typeof value === "boolean") {
+        return value;
+    }
+    throw new SpecGovError(`Invalid manifest: ${field} must be a boolean.`);
+}
+function numberOrDefault(value, defaultValue, field) {
+    if (value === undefined) {
+        return defaultValue;
+    }
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+        return value;
+    }
+    throw new SpecGovError(`Invalid manifest: ${field} must be a non-negative number.`);
+}

package/dist/match.d.ts

@@ -0,0 +1 @@
+export declare function matchesAny(filePath: string, patterns: string | string[] | undefined): boolean;

package/dist/match.js

@@ -0,0 +1,9 @@
+import picomatch from "picomatch";
+import { normalizePath, toArray } from "./paths.js";
+export function matchesAny(filePath, patterns) {
+    const normalizedPath = normalizePath(filePath);
+    return toArray(patterns).some((pattern) => {
+        const matcher = picomatch(normalizePath(pattern), { dot: true });
+        return matcher(normalizedPath);
+    });
+}

package/dist/paths.d.ts

@@ -0,0 +1,3 @@
+export declare function normalizePath(input: string): string;
+export declare function relativeToCwd(cwd: string, filePath: string): string;
+export declare function toArray(value: string | string[] | undefined): string[];

package/dist/paths.js

@@ -0,0 +1,13 @@
+import path from "node:path";
+export function normalizePath(input) {
+    return input.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+export function relativeToCwd(cwd, filePath) {
+    return normalizePath(path.relative(cwd, filePath));
+}
+export function toArray(value) {
+    if (!value) {
+        return [];
+    }
+    return Array.isArray(value) ? value : [value];
+}

package/dist/report.d.ts

@@ -0,0 +1,6 @@
+import type { EnforcementMode, Finding, ReportStatus, SpecGovReport } from "./types.js";
+export declare function evaluateStatus(findings: Finding[], mode: EnforcementMode): ReportStatus;
+export declare function makeReport(input: Omit<SpecGovReport, "status" | "summary">): SpecGovReport;
+export declare function exitCodeForReport(report: SpecGovReport): number;
+export declare function renderReport(report: SpecGovReport, format?: "json" | "markdown"): string;
+export declare function renderMarkdownReport(report: SpecGovReport): string;

package/dist/report.js

@@ -0,0 +1,95 @@
+export function evaluateStatus(findings, mode) {
+    if (findings.some((finding) => finding.severity === "error")) {
+        return "fail";
+    }
+    if (findings.some((finding) => finding.severity === "warning")) {
+        return mode === "strict" ? "fail" : "warn";
+    }
+    return "pass";
+}
+export function makeReport(input) {
+    const status = evaluateStatus(input.findings, input.mode);
+    return {
+        ...input,
+        status,
+        summary: {
+            findings: input.findings.length,
+            errors: input.findings.filter((finding) => finding.severity === "error")
+                .length,
+            warnings: input.findings.filter((finding) => finding.severity === "warning").length,
+            infos: input.findings.filter((finding) => finding.severity === "info")
+                .length,
+        },
+    };
+}
+export function exitCodeForReport(report) {
+    if (report.status === "error") {
+        return 2;
+    }
+    if (report.status === "fail") {
+        return 1;
+    }
+    return 0;
+}
+export function renderReport(report, format = "markdown") {
+    if (format === "json") {
+        return `${JSON.stringify(report, null, 2)}\n`;
+    }
+    return renderMarkdownReport(report);
+}
+export function renderMarkdownReport(report) {
+    const lines = [
+        `# SpecGov ${report.command} report`,
+        "",
+        `Status: **${report.status}**`,
+        `Mode: \`${report.mode}\``,
+        `Findings: ${report.summary.findings} (${report.summary.errors} errors, ${report.summary.warnings} warnings, ${report.summary.infos} info)`,
+        "",
+    ];
+    if (report.changedFiles?.length) {
+        lines.push("## Changed Files", "");
+        for (const file of report.changedFiles) {
+            lines.push(`- \`${file}\``);
+        }
+        lines.push("");
+    }
+    if (report.artifacts) {
+        lines.push("## Governed Artifacts", "");
+        if (report.artifacts.length === 0) {
+            lines.push("No governed artifacts were discovered.", "");
+        }
+        else {
+            for (const artifact of report.artifacts) {
+                const status = artifact.status ? `, status: ${artifact.status}` : "";
+                const owner = artifact.owner ? `, owner: ${artifact.owner}` : "";
+                lines.push(`- \`${artifact.path}\` (${artifact.kind}${status}${owner})`);
+            }
+            lines.push("");
+        }
+    }
+    lines.push("## Findings", "");
+    if (report.findings.length === 0) {
+        lines.push("No findings.", "");
+    }
+    else {
+        for (const finding of report.findings) {
+            lines.push(`- **${finding.severity.toUpperCase()} ${finding.code}**: ${finding.message}`);
+            if (finding.file) {
+                lines.push(`  - File: \`${finding.file}\``);
+            }
+            if (finding.relatedFiles?.length) {
+                lines.push(`  - Related: ${finding.relatedFiles.map((file) => `\`${file}\``).join(", ")}`);
+            }
+            if (finding.suggestion) {
+                lines.push(`  - Suggestion: ${finding.suggestion}`);
+            }
+        }
+        lines.push("");
+    }
+    if (report.trace) {
+        lines.push("## Trace Summary", "");
+        lines.push(`Artifacts: ${report.trace.artifacts.length}`);
+        lines.push(`Mappings: ${report.trace.mappings.length}`, "");
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/types.d.ts

@@ -0,0 +1,84 @@
+export type EnforcementMode = "advisory" | "strict";
+export type ArtifactStatus = "draft" | "active" | "superseded" | "deprecated" | "archived";
+export type ReportStatus = "pass" | "warn" | "fail" | "error";
+export type Severity = "info" | "warning" | "error";
+export interface ArtifactRule {
+    path: string | string[];
+    kind: string;
+    owner?: string;
+    status?: ArtifactStatus;
+}
+export interface MappingRule {
+    code: string | string[];
+    specs: string | string[];
+    description?: string;
+}
+export interface GovernanceRules {
+    require_spec_impact_for_code_changes: boolean;
+    require_lifecycle_status: boolean;
+    require_owner_for_active_specs: boolean;
+    stale_after_days: number;
+}
+export interface SpecGovConfig {
+    version: number;
+    mode: EnforcementMode;
+    artifacts: ArtifactRule[];
+    mappings: MappingRule[];
+    rules: GovernanceRules;
+    ignore: string[];
+}
+export interface ArtifactMetadata {
+    status?: ArtifactStatus;
+    owner?: string;
+    last_verified?: string;
+    superseded_by?: string;
+}
+export interface GovernedArtifact {
+    path: string;
+    kind: string;
+    owner?: string;
+    status?: ArtifactStatus;
+    lastVerified?: string;
+    supersededBy?: string;
+}
+export interface ArtifactDiscovery {
+    artifacts: GovernedArtifact[];
+    ruleMatchCounts: Array<{
+        path: string | string[];
+        kind: string;
+        count: number;
+    }>;
+}
+export interface Finding {
+    code: string;
+    severity: Severity;
+    message: string;
+    file?: string;
+    relatedFiles?: string[];
+    suggestion?: string;
+}
+export interface SpecGovReport {
+    command: string;
+    status: ReportStatus;
+    mode: EnforcementMode;
+    summary: {
+        findings: number;
+        errors: number;
+        warnings: number;
+        infos: number;
+    };
+    findings: Finding[];
+    artifacts?: GovernedArtifact[];
+    changedFiles?: string[];
+    trace?: TraceIndex;
+}
+export interface TraceIndex {
+    generatedAt: string;
+    artifacts: GovernedArtifact[];
+    mappings: Array<{
+        code: string[];
+        specs: string[];
+        matchedArtifacts: string[];
+        description?: string;
+    }>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "specgov",
+  "version": "0.1.0",
+  "description": "Spec governance layer for Git repositories.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "specgov": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "action.yml",
+    "README.md",
+    "RELEASING.md",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json && npm run build:action",
+    "build:action": "ncc build src/action.ts -o dist/action -m --license licenses.txt",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "format:check": "prettier --check ."
+  },
+  "keywords": [
+    "specs",
+    "governance",
+    "git",
+    "requirements",
+    "traceability",
+    "github-action"
+  ],
+  "author": "Fernando Paladini",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paladini/specgov.git"
+  },
+  "bugs": {
+    "url": "https://github.com/paladini/specgov/issues"
+  },
+  "homepage": "https://github.com/paladini/specgov#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@actions/core": "^3.0.1",
+    "commander": "^15.0.0",
+    "fast-glob": "^3.3.3",
+    "picomatch": "^4.0.4",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.0.1",
+    "@types/picomatch": "^4.0.3",
+    "@vercel/ncc": "^0.44.0",
+    "eslint": "^10.6.0",
+    "prettier": "^3.9.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.62.0",
+    "vitest": "^4.1.9"
+  }
+}