@devtrack-solution/codesdd 1.2.3 → 1.2.4

package/dist/core/sdd/plugin-sdk-contract.js

@@ -0,0 +1,268 @@
+import { toJSONSchema, z } from 'zod';
+const JSON_SCHEMA_DRAFT = 'https://json-schema.org/draft/2020-12/schema';
+export const CODESDD_PLUGIN_SDK_PACKAGE_NAME = '@devtrack-solution/codesdd-plugin-sdk';
+export const CODESDD_PLUGIN_PACKAGE_PREFIX = '@devtrack-solution/codesdd-plugin-';
+const SDK_PACKAGE_PATTERN = /^@devtrack-solution\/codesdd-plugin-sdk$/;
+const PLUGIN_PACKAGE_PATTERN = /^@devtrack-solution\/codesdd-plugin-[a-z0-9][a-z0-9-]*$/;
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+const SEMVER_RANGE_PATTERN = /^(?:[~^]?\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?|[<>]=?\d+\.\d+\.\d+(?:\s+<\d+\.\d+\.\d+)?|\*)$/;
+const FEATURE_REF_PATTERN = /^FEAT-\d{4}$/;
+const DECISION_REF_PATTERN = /^(?:ADR|DEB|EPIC|FEAT|INS)-\d{4}$/;
+const OPERATION_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const SAFE_RELATIVE_PATH_PATTERN = /^(?!\/)(?![A-Za-z]:[\\/])(?!.*(?:^|[\\/])\.\.(?:[\\/]|$)).+$/;
+const jsonObjectSchema = z.record(z.string(), z.unknown());
+export const pluginRuntimeLanguageSchema = z.enum([
+    'typescript',
+    'javascript',
+    'python',
+    'java',
+    'go',
+    'rust',
+    'csharp',
+    'php',
+    'ruby',
+    'shell',
+    'other',
+]);
+export const pluginRuntimeBridgeSchema = z.enum([
+    'node-library',
+    'stdio-json',
+    'process-cli',
+    'http-local',
+    'container',
+    'wasm',
+]);
+export const pluginRuntimeTransportSchema = z.enum([
+    'sdk-call',
+    'stdin-json',
+    'stdout-json',
+    'file-envelope',
+    'http-json',
+]);
+export const pluginPackageKindSchema = z.enum([
+    'frontend',
+    'backend',
+    'full-stack',
+    'generator',
+    'validator',
+    'evidence',
+    'agent-adapter',
+    'policy-pack',
+]);
+export const pluginPackageGovernanceSchema = z
+    .object({
+    package_name: z.string().regex(PLUGIN_PACKAGE_PATTERN),
+    sdk_package: z.string().regex(SDK_PACKAGE_PATTERN).default(CODESDD_PLUGIN_SDK_PACKAGE_NAME),
+    sdk_version: z.string().regex(SEMVER_RANGE_PATTERN).default('*'),
+    package_kind: pluginPackageKindSchema,
+    versioning: z.literal('semver').default('semver'),
+    registry: z.enum(['workspace', 'npm', 'private-npm', 'artifact-registry', 'custom']).default('workspace'),
+    keywords: z.array(z.string().min(1)).default([]),
+    internal_package: z.boolean().default(false),
+})
+    .superRefine((value, context) => {
+    const requiredKeywords = ['codesdd-plugin', value.package_kind];
+    for (const keyword of requiredKeywords) {
+        if (!value.keywords.includes(keyword)) {
+            context.addIssue({
+                code: 'custom',
+                path: ['keywords'],
+                message: `Plugin package governance must include keyword '${keyword}'.`,
+            });
+        }
+    }
+});
+export const pluginLanguageRuntimeSchema = z
+    .object({
+    language: pluginRuntimeLanguageSchema,
+    runtime: z.string().min(1),
+    bridge: pluginRuntimeBridgeSchema,
+    input_transport: pluginRuntimeTransportSchema,
+    output_transport: pluginRuntimeTransportSchema,
+    command: z.string().min(1).optional(),
+    args: z.array(z.string()).default([]),
+    package_manager: z.string().min(1).optional(),
+    min_versions: z.record(z.string(), z.string()).default({}),
+    env_allowlist: z.array(z.string().regex(/^[A-Z_][A-Z0-9_]*$/)).default([]),
+})
+    .superRefine((runtime, context) => {
+    const nodeNative = runtime.language === 'typescript' || runtime.language === 'javascript';
+    if (runtime.bridge === 'node-library' && !nodeNative) {
+        context.addIssue({
+            code: 'custom',
+            path: ['bridge'],
+            message: 'node-library bridge is only valid for TypeScript or JavaScript plugins.',
+        });
+    }
+    if (runtime.bridge !== 'node-library' && !runtime.command) {
+        context.addIssue({
+            code: 'custom',
+            path: ['command'],
+            message: 'Non Node-library plugin runtimes must declare an executable command.',
+        });
+    }
+    if (runtime.bridge === 'stdio-json' && runtime.input_transport !== 'stdin-json') {
+        context.addIssue({
+            code: 'custom',
+            path: ['input_transport'],
+            message: 'stdio-json runtimes must receive invocation envelopes through stdin-json.',
+        });
+    }
+    if (runtime.bridge === 'stdio-json' && runtime.output_transport !== 'stdout-json') {
+        context.addIssue({
+            code: 'custom',
+            path: ['output_transport'],
+            message: 'stdio-json runtimes must emit responses through stdout-json.',
+        });
+    }
+});
+export const pluginArtifactLayerSchema = z.enum([
+    'root',
+    'domain',
+    'application',
+    'infrastructure',
+    'presentation',
+    'shared',
+    'tests',
+    'docs',
+    'sdd',
+    'config',
+    'assets',
+]);
+export const pluginArtifactKindSchema = z.enum([
+    'source',
+    'test',
+    'documentation',
+    'configuration',
+    'schema',
+    'evidence',
+    'migration',
+    'asset',
+    'package-metadata',
+]);
+export const pluginArtifactRoleSchema = z.enum([
+    'interface',
+    'type',
+    'implementation',
+    'abstraction',
+    'business-object',
+    'value-object',
+    'entity',
+    'repository-port',
+    'use-case',
+    'service',
+    'handler',
+    'adapter',
+    'mapper',
+    'module',
+    'controller',
+    'dto',
+    'validator',
+    'policy',
+    'manifest',
+    'fixture',
+    'test',
+    'documentation',
+    'evidence',
+]);
+export const pluginArtifactOperationSchema = z.enum([
+    'planned',
+    'created',
+    'modified',
+    'deleted',
+    'unchanged',
+    'validated',
+]);
+export const pluginArtifactMapEntrySchema = z
+    .object({
+    path: z.string().regex(SAFE_RELATIVE_PATH_PATTERN),
+    operation: pluginArtifactOperationSchema,
+    artifact_kind: pluginArtifactKindSchema,
+    role: pluginArtifactRoleSchema,
+    layer: pluginArtifactLayerSchema,
+    content_type: z.string().min(1),
+    reason: z.string().min(1),
+    language: pluginRuntimeLanguageSchema.optional(),
+    context: z.string().min(1).optional(),
+    implementation: z.enum(['concrete', 'abstract', 'contract', 'generated', 'manual']).default('manual'),
+    decision_refs: z.array(z.string().regex(DECISION_REF_PATTERN)).default([]),
+    source_refs: z.array(z.string().min(1)).default([]),
+    tags: z.array(z.string().min(1)).default([]),
+    metadata: jsonObjectSchema.default({}),
+})
+    .superRefine((entry, context) => {
+    if (entry.layer === 'domain' && entry.role === 'repository-port') {
+        context.addIssue({
+            code: 'custom',
+            path: ['role'],
+            message: 'Repository ports in new Foundation BO-pattern contexts belong in application ports/out, not domain.',
+        });
+    }
+    if (entry.layer === 'domain' && entry.role === 'entity' && !entry.decision_refs.some((ref) => ref.startsWith('ADR-'))) {
+        context.addIssue({
+            code: 'custom',
+            path: ['decision_refs'],
+            message: 'Domain entities require an ADR reference unless they are part of an approved legacy entity-pattern context.',
+        });
+    }
+});
+export const pluginArtifactMapSchema = z.object({
+    schema_version: z.literal(1),
+    sdk_package: z.literal(CODESDD_PLUGIN_SDK_PACKAGE_NAME).default(CODESDD_PLUGIN_SDK_PACKAGE_NAME),
+    feature_ref: z.string().regex(FEATURE_REF_PATTERN).optional(),
+    operation_id: z.string().regex(OPERATION_ID_PATTERN).optional(),
+    plugin_ref: z
+        .object({
+        id: z.string().min(1),
+        version: z.string().regex(SEMVER_PATTERN),
+    })
+        .optional(),
+    generated_at: z.string().datetime(),
+    artifacts: z.array(pluginArtifactMapEntrySchema).default([]),
+});
+export function buildPluginPackageName(pluginId) {
+    const normalized = pluginId
+        .trim()
+        .toLowerCase()
+        .replace(/^codesdd-plugin-/u, '')
+        .replace(/[^a-z0-9]+/gu, '-')
+        .replace(/^-+|-+$/gu, '');
+    if (!normalized) {
+        throw new Error('Plugin id cannot produce an empty package name.');
+    }
+    return `${CODESDD_PLUGIN_PACKAGE_PREFIX}${normalized}`;
+}
+export function validatePluginPackageGovernance(value, sourceLabel = 'plugin package governance') {
+    const result = pluginPackageGovernanceSchema.safeParse(value);
+    if (!result.success) {
+        throw new Error(`${sourceLabel} validation failed: ${result.error.issues.map(formatIssue).join('; ')}`);
+    }
+    return result.data;
+}
+export function validatePluginArtifactMap(value, sourceLabel = 'plugin artifact map') {
+    const result = pluginArtifactMapSchema.safeParse(value);
+    if (!result.success) {
+        throw new Error(`${sourceLabel} validation failed: ${result.error.issues.map(formatIssue).join('; ')}`);
+    }
+    return result.data;
+}
+export function buildPluginSdkJsonSchemas() {
+    return {
+        'plugin-package-governance.yaml': normalizeJsonSchema(pluginPackageGovernanceSchema, 'CodeSDD Plugin SDK Package Governance', 'Package naming, versioning, registry, and keyword contract for @devtrack-solution/codesdd-plugin-sdk plugin packages.'),
+        'plugin-language-runtime.yaml': normalizeJsonSchema(pluginLanguageRuntimeSchema, 'CodeSDD Plugin SDK Language Runtime', 'Language-agnostic runtime bridge contract for TypeScript, JavaScript, Python, Java, Go, Rust, C#, shell, and custom plugin implementations.'),
+        'plugin-artifact-map.yaml': normalizeJsonSchema(pluginArtifactMapSchema, 'CodeSDD Plugin SDK Artifact Map', 'Typed file map for plugin-planned artifacts with layer, role, kind, operation, decision refs, and source refs.'),
+    };
+}
+function normalizeJsonSchema(schema, title, description) {
+    return {
+        ...toJSONSchema(schema),
+        $schema: JSON_SCHEMA_DRAFT,
+        title,
+        description,
+    };
+}
+function formatIssue(issue) {
+    const issuePath = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+    return `${issuePath}: ${issue.message}`;
+}
+//# sourceMappingURL=plugin-sdk-contract.js.map

package/dist/core/sdd/plugin-skill-binding.d.ts

@@ -67,8 +67,8 @@ export declare const pluginSkillBindingResolutionSchema: z.ZodObject<{
     schema_version: z.ZodLiteral<1>;
     created_at: z.ZodString;
     status: z.ZodEnum<{
-        resolved: "resolved";
         fallback: "fallback";
+        resolved: "resolved";
     }>;
     request: z.ZodObject<{
         schema_version: z.ZodDefault<z.ZodLiteral<1>>;

package/dist/core/sdd/quality-validation.d.ts

@@ -1,13 +1,13 @@
 import { z } from 'zod';
 export declare const qualityAuthorityRefSchema: z.ZodObject<{
     type: z.ZodEnum<{
+        skill: "skill";
         schema: "schema";
         epic: "epic";
         feature: "feature";
+        foundation: "foundation";
         debate: "debate";
         adr: "adr";
-        skill: "skill";
-        foundation: "foundation";
     }>;
     ref: z.ZodString;
     path: z.ZodOptional<z.ZodString>;
@@ -17,8 +17,8 @@ export declare const qualityAuthorityRefSchema: z.ZodObject<{
 export declare const qualityGateRefSchema: z.ZodObject<{
     id: z.ZodString;
     type: z.ZodEnum<{
-        schema: "schema";
         filesystem: "filesystem";
+        schema: "schema";
         runtime: "runtime";
         evidence: "evidence";
         import: "import";
@@ -52,13 +52,13 @@ export declare const qualityScenarioSchema: z.ZodObject<{
     intent: z.ZodString;
     authority: z.ZodArray<z.ZodObject<{
         type: z.ZodEnum<{
+            skill: "skill";
             schema: "schema";
             epic: "epic";
             feature: "feature";
+            foundation: "foundation";
             debate: "debate";
             adr: "adr";
-            skill: "skill";
-            foundation: "foundation";
         }>;
         ref: z.ZodString;
         path: z.ZodOptional<z.ZodString>;
@@ -79,8 +79,8 @@ export declare const qualityScenarioSchema: z.ZodObject<{
     gates: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         type: z.ZodEnum<{
-            schema: "schema";
             filesystem: "filesystem";
+            schema: "schema";
             runtime: "runtime";
             evidence: "evidence";
             import: "import";
@@ -117,13 +117,13 @@ export declare const qualityArchitectureSchema: z.ZodObject<{
     stack: z.ZodString;
     authority: z.ZodArray<z.ZodObject<{
         type: z.ZodEnum<{
+            skill: "skill";
             schema: "schema";
             epic: "epic";
             feature: "feature";
+            foundation: "foundation";
             debate: "debate";
             adr: "adr";
-            skill: "skill";
-            foundation: "foundation";
         }>;
         ref: z.ZodString;
         path: z.ZodOptional<z.ZodString>;
@@ -158,8 +158,8 @@ export declare const qualityRunFindingSchema: z.ZodObject<{
     code: z.ZodString;
     severity: z.ZodEnum<{
         error: "error";
-        warn: "warn";
         info: "info";
+        warn: "warn";
         blocker: "blocker";
     }>;
     message: z.ZodString;
@@ -202,8 +202,8 @@ export declare const qualityRunSchema: z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
             error: "error";
-            warn: "warn";
             info: "info";
+            warn: "warn";
             blocker: "blocker";
         }>;
         message: z.ZodString;
@@ -271,8 +271,8 @@ export declare const qualityEvidenceBundleSchema: z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
                 error: "error";
-                warn: "warn";
                 info: "info";
+                warn: "warn";
                 blocker: "blocker";
             }>;
             message: z.ZodString;
@@ -297,13 +297,13 @@ export declare const qualityEvidenceBundleSchema: z.ZodObject<{
         intent: z.ZodString;
         authority: z.ZodArray<z.ZodObject<{
             type: z.ZodEnum<{
+                skill: "skill";
                 schema: "schema";
                 epic: "epic";
                 feature: "feature";
+                foundation: "foundation";
                 debate: "debate";
                 adr: "adr";
-                skill: "skill";
-                foundation: "foundation";
             }>;
             ref: z.ZodString;
             path: z.ZodOptional<z.ZodString>;
@@ -324,8 +324,8 @@ export declare const qualityEvidenceBundleSchema: z.ZodObject<{
         gates: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             type: z.ZodEnum<{
-                schema: "schema";
                 filesystem: "filesystem";
+                schema: "schema";
                 runtime: "runtime";
                 evidence: "evidence";
                 import: "import";
@@ -354,13 +354,13 @@ export declare const qualityEvidenceBundleSchema: z.ZodObject<{
         stack: z.ZodString;
         authority: z.ZodArray<z.ZodObject<{
             type: z.ZodEnum<{
+                skill: "skill";
                 schema: "schema";
                 epic: "epic";
                 feature: "feature";
+                foundation: "foundation";
                 debate: "debate";
                 adr: "adr";
-                skill: "skill";
-                foundation: "foundation";
             }>;
             ref: z.ZodString;
             path: z.ZodOptional<z.ZodString>;
@@ -426,6 +426,79 @@ export declare const qualityEvidenceBundleSchema: z.ZodObject<{
             checksum_before: z.ZodOptional<z.ZodString>;
             checksum_after: z.ZodOptional<z.ZodString>;
             content_type: z.ZodOptional<z.ZodString>;
+            artifact_kind: z.ZodOptional<z.ZodEnum<{
+                documentation: "documentation";
+                schema: "schema";
+                configuration: "configuration";
+                source: "source";
+                migration: "migration";
+                evidence: "evidence";
+                test: "test";
+                asset: "asset";
+                "package-metadata": "package-metadata";
+            }>>;
+            role: z.ZodOptional<z.ZodEnum<{
+                documentation: "documentation";
+                type: "type";
+                validator: "validator";
+                evidence: "evidence";
+                test: "test";
+                interface: "interface";
+                implementation: "implementation";
+                abstraction: "abstraction";
+                "business-object": "business-object";
+                "value-object": "value-object";
+                entity: "entity";
+                "repository-port": "repository-port";
+                "use-case": "use-case";
+                service: "service";
+                handler: "handler";
+                adapter: "adapter";
+                mapper: "mapper";
+                module: "module";
+                controller: "controller";
+                dto: "dto";
+                policy: "policy";
+                manifest: "manifest";
+                fixture: "fixture";
+            }>>;
+            layer: z.ZodOptional<z.ZodEnum<{
+                sdd: "sdd";
+                config: "config";
+                domain: "domain";
+                docs: "docs";
+                root: "root";
+                application: "application";
+                infrastructure: "infrastructure";
+                presentation: "presentation";
+                shared: "shared";
+                tests: "tests";
+                assets: "assets";
+            }>>;
+            language: z.ZodOptional<z.ZodEnum<{
+                shell: "shell";
+                other: "other";
+                typescript: "typescript";
+                javascript: "javascript";
+                python: "python";
+                java: "java";
+                go: "go";
+                rust: "rust";
+                csharp: "csharp";
+                php: "php";
+                ruby: "ruby";
+            }>>;
+            context: z.ZodOptional<z.ZodString>;
+            implementation: z.ZodOptional<z.ZodEnum<{
+                contract: "contract";
+                manual: "manual";
+                concrete: "concrete";
+                abstract: "abstract";
+                generated: "generated";
+            }>>;
+            decision_refs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            source_refs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>>;
         validation_evidence: z.ZodDefault<z.ZodArray<z.ZodObject<{
             command: z.ZodString;

package/dist/core/sdd/release-readiness.d.ts

@@ -0,0 +1,68 @@
+export type ReleaseReadinessStatus = 'ready' | 'warning' | 'blocked';
+export interface ReleaseReadinessCheck {
+    id: string;
+    status: 'pass' | 'warn' | 'fail';
+    classification?: ReleaseReadinessClassification;
+    owner?: string;
+    delta?: string;
+    next_action?: string;
+    history?: string[];
+    exception?: ReleaseReadinessExceptionState;
+    summary: string;
+    evidence?: string;
+}
+export type ReleaseReadinessClassification = 'passed' | 'failed' | 'excepted' | 'follow_up' | 'not_applicable';
+export interface ReleaseReadinessExceptionState {
+    status: 'none' | 'active' | 'stale';
+    source?: string;
+    scope?: string;
+    reason?: string;
+    accepted_risk?: string;
+    compensating_control?: string;
+    review_deadline?: string;
+    approver?: string;
+}
+export interface ReleaseReadinessReport {
+    schema_version: 1;
+    status: ReleaseReadinessStatus;
+    generated_at: string;
+    blocker_classification: Array<{
+        check_id: string;
+        classification: ReleaseReadinessClassification;
+        owner: string;
+        next_action: string;
+        stale_exception: boolean;
+    }>;
+    blockers: string[];
+    warnings: string[];
+    checks: ReleaseReadinessCheck[];
+    handoff_sections: ReleaseReadinessHandoffSection[];
+    ci_parity_commands: string[];
+}
+export type ReleaseReadinessHandoffSectionId = 'governance' | 'tests' | 'release_readiness' | 'git_cleanliness' | 'runtime_env';
+export interface ReleaseReadinessHandoffSection {
+    id: ReleaseReadinessHandoffSectionId;
+    title: string;
+    status: ReleaseReadinessStatus;
+    owner: string;
+    next_action: string;
+    checks: ReleaseReadinessCheck[];
+    evidence: {
+        json_snapshot: {
+            section_id: ReleaseReadinessHandoffSectionId;
+            status: ReleaseReadinessStatus;
+            checks: Array<{
+                id: string;
+                status: ReleaseReadinessCheck['status'];
+                classification: ReleaseReadinessClassification;
+                owner: string;
+                next_action: string;
+                evidence?: string;
+            }>;
+        };
+        human_snapshot: string[];
+    };
+}
+export declare function evaluateReleaseReadiness(projectRoot: string): Promise<ReleaseReadinessReport>;
+export declare function formatReleaseReadinessReport(report: ReleaseReadinessReport): string;
+//# sourceMappingURL=release-readiness.d.ts.map