specgov 0.1.0

package/dist/action.js

@@ -0,0 +1,45 @@
+import * as core from "@actions/core";
+import { runCheckPr } from "./checks.js";
+import { loadConfig } from "./manifest.js";
+import { renderMarkdownReport } from "./report.js";
+async function main() {
+    try {
+        const cwd = process.cwd();
+        const configPath = core.getInput("config") || ".specgov.yml";
+        const modeInput = core.getInput("mode") || undefined;
+        const mode = modeInput ? parseMode(modeInput) : undefined;
+        const baseRef = core.getInput("base-ref") || undefined;
+        const headRef = core.getInput("head-ref") || undefined;
+        const changedFiles = core
+            .getMultilineInput("changed-files")
+            .filter(Boolean);
+        const config = await loadConfig(cwd, configPath);
+        const report = await runCheckPr({
+            cwd,
+            config,
+            mode,
+            baseRef,
+            headRef,
+            changedFiles,
+        });
+        const markdown = renderMarkdownReport(report);
+        await core.summary.addRaw(markdown).write();
+        core.info(markdown);
+        core.setOutput("status", report.status);
+        core.setOutput("report-json", JSON.stringify(report));
+        if (report.status === "fail") {
+            core.setFailed(`SpecGov failed with ${report.summary.findings} finding(s).`);
+        }
+    }
+    catch (error) {
+        core.setOutput("status", "error");
+        core.setFailed(error.message);
+    }
+}
+function parseMode(value) {
+    if (value === "advisory" || value === "strict") {
+        return value;
+    }
+    throw new Error('mode must be "advisory" or "strict".');
+}
+await main();

package/dist/artifacts.d.ts

@@ -0,0 +1,6 @@
+import type { ArtifactDiscovery, ArtifactMetadata, Finding, GovernedArtifact, SpecGovConfig } from "./types.js";
+export declare function discoverArtifacts(config: SpecGovConfig, cwd: string): Promise<ArtifactDiscovery>;
+export declare function readArtifactMetadata(filePath: string): Promise<ArtifactMetadata>;
+export declare function buildArtifactFindings(config: SpecGovConfig, discovery: ArtifactDiscovery, now?: Date): Finding[];
+export declare function artifactPathsMatching(artifacts: GovernedArtifact[], patterns: string | string[]): string[];
+export declare function isArtifactPath(config: SpecGovConfig, filePath: string): boolean;

package/dist/artifacts.js

@@ -0,0 +1,151 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import fg from "fast-glob";
+import { parse } from "yaml";
+import { matchesAny } from "./match.js";
+import { normalizePath, toArray } from "./paths.js";
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
+const STATUS_VALUES = [
+    "draft",
+    "active",
+    "superseded",
+    "deprecated",
+    "archived",
+];
+export async function discoverArtifacts(config, cwd) {
+    const artifactsByPath = new Map();
+    const ruleMatchCounts = [];
+    for (const rule of config.artifacts) {
+        const entries = await fg(toArray(rule.path), {
+            cwd,
+            onlyFiles: true,
+            dot: true,
+            ignore: config.ignore,
+        });
+        ruleMatchCounts.push({
+            path: rule.path,
+            kind: rule.kind,
+            count: entries.length,
+        });
+        for (const entry of entries) {
+            const relativePath = normalizePath(entry);
+            if (artifactsByPath.has(relativePath)) {
+                continue;
+            }
+            const metadata = await readArtifactMetadata(path.resolve(cwd, entry));
+            artifactsByPath.set(relativePath, {
+                path: relativePath,
+                kind: rule.kind,
+                owner: metadata.owner ?? rule.owner,
+                status: metadata.status ?? rule.status,
+                lastVerified: metadata.last_verified,
+                supersededBy: metadata.superseded_by,
+            });
+        }
+    }
+    return {
+        artifacts: [...artifactsByPath.values()].sort((left, right) => left.path.localeCompare(right.path)),
+        ruleMatchCounts,
+    };
+}
+export async function readArtifactMetadata(filePath) {
+    const text = await fs.readFile(filePath, "utf8");
+    const match = text.match(FRONTMATTER);
+    if (!match?.[1]) {
+        return {};
+    }
+    const parsed = parse(match[1]);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {};
+    }
+    const raw = parsed;
+    const metadata = {};
+    if (typeof raw.status === "string" &&
+        STATUS_VALUES.includes(raw.status)) {
+        metadata.status = raw.status;
+    }
+    if (typeof raw.owner === "string") {
+        metadata.owner = raw.owner;
+    }
+    if (typeof raw.last_verified === "string") {
+        metadata.last_verified = raw.last_verified;
+    }
+    if (typeof raw.superseded_by === "string") {
+        metadata.superseded_by = raw.superseded_by;
+    }
+    return metadata;
+}
+export function buildArtifactFindings(config, discovery, now = new Date()) {
+    const findings = [];
+    for (const rule of discovery.ruleMatchCounts) {
+        if (rule.count === 0) {
+            findings.push({
+                code: "ARTIFACT_GLOB_EMPTY",
+                severity: "warning",
+                message: `Artifact glob for ${rule.kind} matched no files.`,
+                relatedFiles: toArray(rule.path),
+                suggestion: "Update the glob or add the governed artifact files.",
+            });
+        }
+    }
+    for (const artifact of discovery.artifacts) {
+        if (config.rules.require_lifecycle_status && !artifact.status) {
+            findings.push({
+                code: "LIFECYCLE_STATUS_MISSING",
+                severity: "warning",
+                message: `Governed artifact ${artifact.path} has no lifecycle status.`,
+                file: artifact.path,
+                suggestion: "Add YAML frontmatter with status: active, draft, superseded, deprecated, or archived.",
+            });
+        }
+        if (config.rules.require_owner_for_active_specs &&
+            artifact.status === "active" &&
+            !artifact.owner) {
+            findings.push({
+                code: "ACTIVE_OWNER_MISSING",
+                severity: "warning",
+                message: `Active governed artifact ${artifact.path} has no owner.`,
+                file: artifact.path,
+                suggestion: "Add owner metadata in frontmatter or the artifact rule.",
+            });
+        }
+        if (artifact.status === "superseded" && !artifact.supersededBy) {
+            findings.push({
+                code: "SUPERSEDED_TARGET_MISSING",
+                severity: "warning",
+                message: `Superseded artifact ${artifact.path} does not declare superseded_by.`,
+                file: artifact.path,
+                suggestion: "Add superseded_by metadata pointing to the replacement artifact.",
+            });
+        }
+        if (artifact.lastVerified && config.rules.stale_after_days > 0) {
+            const ageDays = daysBetween(artifact.lastVerified, now);
+            if (ageDays !== undefined && ageDays > config.rules.stale_after_days) {
+                findings.push({
+                    code: "ARTIFACT_STALE",
+                    severity: "warning",
+                    message: `Governed artifact ${artifact.path} was last verified ${ageDays} days ago.`,
+                    file: artifact.path,
+                    suggestion: "Review the artifact and update last_verified if it still matches reality.",
+                });
+            }
+        }
+    }
+    return findings;
+}
+export function artifactPathsMatching(artifacts, patterns) {
+    return artifacts
+        .filter((artifact) => matchesAny(artifact.path, patterns))
+        .map((artifact) => artifact.path);
+}
+export function isArtifactPath(config, filePath) {
+    return config.artifacts.some((rule) => matchesAny(filePath, rule.path));
+}
+function daysBetween(dateText, now) {
+    const parsed = new Date(`${dateText}T00:00:00Z`);
+    if (Number.isNaN(parsed.getTime())) {
+        return undefined;
+    }
+    const diffMs = now.getTime() - parsed.getTime();
+    return Math.floor(diffMs / 86_400_000);
+}

package/dist/checks.d.ts

@@ -0,0 +1,16 @@
+import type { SpecGovConfig, SpecGovReport, TraceIndex } from "./types.js";
+interface BaseOptions {
+    cwd: string;
+    config: SpecGovConfig;
+}
+export interface CheckPrOptions extends BaseOptions {
+    baseRef?: string;
+    headRef?: string;
+    changedFiles?: string[];
+    mode?: "advisory" | "strict";
+}
+export declare function runScan(options: BaseOptions): Promise<SpecGovReport>;
+export declare function runCheckPr(options: CheckPrOptions): Promise<SpecGovReport>;
+export declare function runTrace(options: BaseOptions): Promise<TraceIndex>;
+export declare function runDrift(options: BaseOptions): Promise<SpecGovReport>;
+export {};

package/dist/checks.js

@@ -0,0 +1,121 @@
+import { artifactPathsMatching, buildArtifactFindings, discoverArtifacts, isArtifactPath, } from "./artifacts.js";
+import { getChangedFiles } from "./git.js";
+import { matchesAny } from "./match.js";
+import { toArray } from "./paths.js";
+import { makeReport } from "./report.js";
+export async function runScan(options) {
+    const discovery = await discoverArtifacts(options.config, options.cwd);
+    const findings = buildArtifactFindings(options.config, discovery);
+    return makeReport({
+        command: "scan",
+        mode: options.config.mode,
+        findings,
+        artifacts: discovery.artifacts,
+    });
+}
+export async function runCheckPr(options) {
+    const config = options.mode
+        ? { ...options.config, mode: options.mode }
+        : options.config;
+    const discovery = await discoverArtifacts(config, options.cwd);
+    const changedFiles = await getChangedFiles({
+        cwd: options.cwd,
+        baseRef: options.baseRef,
+        headRef: options.headRef,
+        explicitFiles: options.changedFiles,
+    });
+    const filteredChangedFiles = changedFiles.filter((file) => !matchesAny(file, config.ignore));
+    const findings = [
+        ...buildArtifactFindings(config, discovery),
+        ...buildImpactFindings(config, filteredChangedFiles),
+    ];
+    return makeReport({
+        command: "check-pr",
+        mode: config.mode,
+        findings,
+        artifacts: discovery.artifacts,
+        changedFiles: filteredChangedFiles,
+    });
+}
+export async function runTrace(options) {
+    const discovery = await discoverArtifacts(options.config, options.cwd);
+    return {
+        generatedAt: new Date().toISOString(),
+        artifacts: discovery.artifacts,
+        mappings: options.config.mappings.map((mapping) => ({
+            code: toArray(mapping.code),
+            specs: toArray(mapping.specs),
+            matchedArtifacts: artifactPathsMatching(discovery.artifacts, mapping.specs),
+            description: mapping.description,
+        })),
+    };
+}
+export async function runDrift(options) {
+    const discovery = await discoverArtifacts(options.config, options.cwd);
+    const trace = await runTrace(options);
+    const findings = [
+        ...buildArtifactFindings(options.config, discovery),
+        ...buildOrphanFindings(options.config, discovery.artifacts.map((artifact) => artifact.path)),
+    ];
+    return makeReport({
+        command: "drift",
+        mode: options.config.mode,
+        findings,
+        artifacts: discovery.artifacts,
+        trace,
+    });
+}
+function buildImpactFindings(config, changedFiles) {
+    const findings = [];
+    const mappedCodeFiles = new Set();
+    for (const mapping of config.mappings) {
+        const changedCode = changedFiles.filter((file) => matchesAny(file, mapping.code));
+        if (changedCode.length === 0) {
+            continue;
+        }
+        for (const file of changedCode) {
+            mappedCodeFiles.add(file);
+        }
+        const changedSpecs = changedFiles.filter((file) => matchesAny(file, mapping.specs));
+        if (changedSpecs.length === 0) {
+            findings.push({
+                code: "SPEC_IMPACT_MISSING",
+                severity: "warning",
+                message: `Code changed under ${toArray(mapping.code).join(", ")} without a related spec artifact change.`,
+                relatedFiles: [...changedCode, ...toArray(mapping.specs)],
+                suggestion: "Update a mapped spec artifact or run in advisory mode until this mapping is ready to enforce.",
+            });
+        }
+    }
+    if (config.rules.require_spec_impact_for_code_changes) {
+        for (const file of changedFiles) {
+            const isMapped = mappedCodeFiles.has(file);
+            const isGovernedArtifact = isArtifactPath(config, file);
+            const isManifest = file === ".specgov.yml";
+            if (!isMapped && !isGovernedArtifact && !isManifest) {
+                findings.push({
+                    code: "CODE_CHANGE_UNMAPPED",
+                    severity: "warning",
+                    message: `Changed file ${file} is not covered by a code-to-spec mapping.`,
+                    file,
+                    suggestion: "Add a mapping for this code area or ignore it explicitly.",
+                });
+            }
+        }
+    }
+    return findings;
+}
+function buildOrphanFindings(config, artifactPaths) {
+    if (config.mappings.length === 0) {
+        return [];
+    }
+    return artifactPaths
+        .filter((artifactPath) => !config.mappings.some((mapping) => matchesAny(artifactPath, mapping.specs)))
+        .map((artifactPath) => ({
+        code: "ARTIFACT_ORPHANED",
+        severity: "info",
+        message: `Governed artifact ${artifactPath} is not referenced by any mapping.`,
+        file: artifactPath,
+        suggestion: "Reference this artifact from a mapping if it should participate in PR impact checks.",
+    }));
+}

package/dist/cli-app.d.ts

@@ -0,0 +1,5 @@
+export interface CliIo {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+}
+export declare function runCli(argv: string[], cwd: string, io: CliIo): Promise<number>;

package/dist/cli-app.js

@@ -0,0 +1,125 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Command, InvalidArgumentError } from "commander";
+import { runCheckPr, runDrift, runScan, runTrace } from "./checks.js";
+import { SpecGovError } from "./errors.js";
+import { DEFAULT_CONFIG_PATH, loadConfig, writeDefaultConfig, } from "./manifest.js";
+import { exitCodeForReport, renderReport } from "./report.js";
+export async function runCli(argv, cwd, io) {
+    const program = new Command();
+    let exitCode = 0;
+    program
+        .name("specgov")
+        .description("Spec governance layer for Git repositories.")
+        .version("0.1.0")
+        .showHelpAfterError()
+        .exitOverride();
+    program.configureOutput({
+        writeOut: (text) => io.stdout(text),
+        writeErr: (text) => io.stderr(text),
+    });
+    program
+        .command("init")
+        .description("Create a .specgov.yml template.")
+        .option("-c, --config <path>", "Manifest path.", DEFAULT_CONFIG_PATH)
+        .option("--force", "Overwrite an existing manifest.", false)
+        .action(async (options) => {
+        await writeDefaultConfig(cwd, options.config, options.force);
+        io.stdout(`Created ${options.config}\n`);
+    });
+    program
+        .command("scan")
+        .description("Discover governed artifacts and validate lifecycle metadata.")
+        .option("-c, --config <path>", "Manifest path.", DEFAULT_CONFIG_PATH)
+        .option("-f, --format <format>", "Output format: markdown or json.", parseFormat, "markdown")
+        .action(async (options) => {
+        const config = await loadConfig(cwd, options.config);
+        const report = await runScan({ cwd, config });
+        io.stdout(renderReport(report, options.format));
+        exitCode = exitCodeForReport(report);
+    });
+    program
+        .command("check-pr")
+        .description("Check changed files for missing spec impact.")
+        .option("-c, --config <path>", "Manifest path.", DEFAULT_CONFIG_PATH)
+        .option("--base-ref <ref>", "Base git ref for comparison.")
+        .option("--head-ref <ref>", "Head git ref for comparison.")
+        .option("--changed-file <path>", "Explicit changed file. Repeatable.", collect, [])
+        .option("--mode <mode>", "Override enforcement mode: advisory or strict.", parseMode)
+        .option("-f, --format <format>", "Output format: markdown or json.", parseFormat, "markdown")
+        .action(async (options) => {
+        const config = await loadConfig(cwd, options.config);
+        const report = await runCheckPr({
+            cwd,
+            config,
+            baseRef: options.baseRef,
+            headRef: options.headRef,
+            changedFiles: options.changedFile,
+            mode: options.mode,
+        });
+        io.stdout(renderReport(report, options.format));
+        exitCode = exitCodeForReport(report);
+    });
+    program
+        .command("trace")
+        .description("Generate a machine-readable trace index.")
+        .option("-c, --config <path>", "Manifest path.", DEFAULT_CONFIG_PATH)
+        .option("--out <path>", "Write trace JSON to a file.")
+        .action(async (options) => {
+        const config = await loadConfig(cwd, options.config);
+        const trace = await runTrace({ cwd, config });
+        const text = `${JSON.stringify(trace, null, 2)}\n`;
+        if (options.out) {
+            await fs.writeFile(path.resolve(cwd, options.out), text, "utf8");
+            io.stdout(`Wrote ${options.out}\n`);
+        }
+        else {
+            io.stdout(text);
+        }
+    });
+    program
+        .command("drift")
+        .description("Report stale, empty, superseded, and orphaned spec artifacts.")
+        .option("-c, --config <path>", "Manifest path.", DEFAULT_CONFIG_PATH)
+        .option("-f, --format <format>", "Output format: markdown or json.", parseFormat, "markdown")
+        .action(async (options) => {
+        const config = await loadConfig(cwd, options.config);
+        const report = await runDrift({ cwd, config });
+        io.stdout(renderReport(report, options.format));
+        exitCode = exitCodeForReport(report);
+    });
+    try {
+        await program.parseAsync(argv, { from: "user" });
+        return exitCode;
+    }
+    catch (error) {
+        if (error instanceof SpecGovError) {
+            io.stderr(`${error.message}\n`);
+            return error.exitCode;
+        }
+        if (isCommanderExit(error)) {
+            return error.exitCode;
+        }
+        io.stderr(`${error.message}\n`);
+        return 2;
+    }
+}
+function parseFormat(value) {
+    if (value === "json" || value === "markdown") {
+        return value;
+    }
+    throw new InvalidArgumentError('format must be "json" or "markdown".');
+}
+function parseMode(value) {
+    if (value === "advisory" || value === "strict") {
+        return value;
+    }
+    throw new InvalidArgumentError('mode must be "advisory" or "strict".');
+}
+function collect(value, previous) {
+    previous.push(value);
+    return previous;
+}
+function isCommanderExit(error) {
+    return Boolean(error && typeof error === "object" && "exitCode" in error);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from "./cli-app.js";
+const exitCode = await runCli(process.argv.slice(2), process.cwd(), {
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+});
+process.exitCode = exitCode;

package/dist/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class SpecGovError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}

package/dist/errors.js

@@ -0,0 +1,8 @@
+export class SpecGovError extends Error {
+    exitCode;
+    constructor(message, exitCode = 2) {
+        super(message);
+        this.name = "SpecGovError";
+        this.exitCode = exitCode;
+    }
+}

package/dist/git.d.ts

@@ -0,0 +1,7 @@
+export interface ChangedFileOptions {
+    cwd: string;
+    baseRef?: string;
+    headRef?: string;
+    explicitFiles?: string[];
+}
+export declare function getChangedFiles(options: ChangedFileOptions): Promise<string[]>;

package/dist/git.js

@@ -0,0 +1,47 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { normalizePath } from "./paths.js";
+const execFileAsync = promisify(execFile);
+export async function getChangedFiles(options) {
+    if (options.explicitFiles && options.explicitFiles.length > 0) {
+        return uniqueNormalized(options.explicitFiles);
+    }
+    if (options.baseRef && options.headRef) {
+        const { stdout } = await execFileAsync("git", [
+            "diff",
+            "--name-only",
+            "--diff-filter=ACMRTUXB",
+            `${options.baseRef}...${options.headRef}`,
+        ], {
+            cwd: options.cwd,
+        });
+        return lines(stdout);
+    }
+    const staged = await gitLines(options.cwd, [
+        "diff",
+        "--name-only",
+        "--cached",
+        "--diff-filter=ACMRTUXB",
+    ]);
+    const unstaged = await gitLines(options.cwd, [
+        "diff",
+        "--name-only",
+        "--diff-filter=ACMRTUXB",
+    ]);
+    const untracked = await gitLines(options.cwd, [
+        "ls-files",
+        "--others",
+        "--exclude-standard",
+    ]);
+    return uniqueNormalized([...staged, ...unstaged, ...untracked]);
+}
+async function gitLines(cwd, args) {
+    const { stdout } = await execFileAsync("git", args, { cwd });
+    return lines(stdout);
+}
+function lines(text) {
+    return uniqueNormalized(text.split(/\r?\n/).filter(Boolean));
+}
+function uniqueNormalized(files) {
+    return [...new Set(files.map(normalizePath))].sort();
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./artifacts.js";
+export * from "./checks.js";
+export * from "./manifest.js";
+export * from "./report.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./artifacts.js";
+export * from "./checks.js";
+export * from "./manifest.js";
+export * from "./report.js";
+export * from "./types.js";

package/dist/manifest.d.ts

@@ -0,0 +1,6 @@
+import type { SpecGovConfig } from "./types.js";
+export declare const DEFAULT_CONFIG_PATH = ".specgov.yml";
+export declare const DEFAULT_CONFIG_TEMPLATE = "version: 1\nmode: advisory\n\nartifacts:\n  - path: \"docs/**/*.md\"\n    kind: documentation\n    owner: docs\n  - path: \"adr/**/*.md\"\n    kind: decision\n    owner: architecture\n  - path: \".specs/**/*.md\"\n    kind: specification\n    owner: engineering\n\nmappings:\n  - code: \"src/**\"\n    specs:\n      - \"docs/**\"\n      - \"adr/**\"\n      - \".specs/**\"\n\nrules:\n  require_spec_impact_for_code_changes: true\n  require_lifecycle_status: false\n  require_owner_for_active_specs: false\n  stale_after_days: 180\n\nignore:\n  - \"node_modules/**\"\n  - \"dist/**\"\n  - \".git/**\"\n";
+export declare function loadConfig(cwd: string, configPath?: string): Promise<SpecGovConfig>;
+export declare function writeDefaultConfig(cwd: string, configPath?: string, force?: boolean): Promise<void>;
+export declare function normalizeConfig(input: unknown, source?: string): SpecGovConfig;