@donartcha/openlag 0.1.0

package/scripts/cli/lint.ts

@@ -0,0 +1,29 @@
+import path from 'path';
+import { runLint, printHumanReport, loadConfig } from '../lint/lint-engine.js';
+import chalk from 'chalk';
+
+export function lintDocs(profile: string, jsonOutput = false, strictWarnings = false) {
+  const docsDir = path.join(process.cwd(), 'docs');
+  const configPath = path.join(process.cwd(), 'openlag.config.yml');
+
+  const config = loadConfig(configPath);
+  
+  const report = runLint(docsDir, configPath, profile);
+
+  if (jsonOutput) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    printHumanReport(report);
+  }
+
+  const failOnWarnings = strictWarnings || config.failOnWarnings;
+
+  let hasErrors = report.summary.errors > 0;
+  if (failOnWarnings && report.summary.warnings > 0) {
+      hasErrors = true;
+  }
+
+  if (hasErrors) {
+     process.exit(1);
+  }
+}

package/scripts/cli/openlag.ts

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+import { execFileSync } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import chalk from 'chalk';
+import { Command } from 'commander';
+
+import { buildPortal } from './build.js';
+import { runDevServer } from './dev.js';
+import { generateData, watchData } from './generate.js';
+import { initProject } from './init.js';
+import { lintDocs } from './lint.js';
+import { resolveViteBin } from './vite-bin.js';
+
+const program = new Command();
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+
+function runVitePreview() {
+  const viteBin = resolveViteBin(import.meta.url);
+  execFileSync(process.execPath, [viteBin, 'preview', '--outDir', path.join(process.cwd(), 'dist')], {
+    cwd: packageRoot,
+    env: {
+      ...process.env,
+      OPENLAG_PROJECT_ROOT: process.cwd(),
+    },
+    stdio: 'inherit',
+  });
+}
+
+program.name('openlag').description('Architecture as Code traceability graph generator').version('0.1.0');
+
+program
+  .command('init')
+  .description('Initialize a new OpenLAG project')
+  .option('-n, --name <name>', 'Project name')
+  .option('-d, --desc <description>', 'Project description')
+  .option('--all', 'Include optional synthetic relations')
+  .action((options) => {
+    initProject(options.name, options.desc, options.all);
+  });
+
+program
+  .command('generate')
+  .description('Generate static graph data from markdown docs')
+  .option('-w, --watch', 'Watch mode')
+  .action((options) => {
+    const docsDir = path.join(process.cwd(), 'docs');
+    const outputDir = path.join(process.cwd(), 'public');
+
+    if (options.watch) {
+      watchData(docsDir, outputDir);
+    } else {
+      generateData(docsDir, outputDir);
+    }
+  });
+
+program
+  .command('dev')
+  .description('Start development server with live data refresh')
+  .action(() => {
+    runDevServer();
+  });
+
+program
+  .command('build')
+  .description('Build the OpenLAG portal for production')
+  .action(() => {
+    buildPortal();
+  });
+
+program
+  .command('lint')
+  .description('Validate architecture documentation')
+  .option('-p, --profile <profile>', 'Lint profile (develop, feature, release)', 'develop')
+  .option('--json', 'Output report in JSON format')
+  .option('--strict', 'Fail on warnings')
+  .action((options) => {
+    lintDocs(options.profile, options.json, options.strict);
+  });
+
+program
+  .command('preview')
+  .description('Preview the production build')
+  .action(() => {
+    runVitePreview();
+  });
+
+program
+  .command('check')
+  .description('Generate graph data and validate architecture documentation')
+  .option('-p, --profile <profile>', 'Lint profile (develop, feature, release)', 'develop')
+  .option('--strict', 'Fail on warnings')
+  .action((options) => {
+    console.log(chalk.blue('Running OpenLAG checks...'));
+
+    const docsDir = path.join(process.cwd(), 'docs');
+    const outputDir = path.join(process.cwd(), 'public');
+
+    try {
+      generateData(docsDir, outputDir);
+      lintDocs(options.profile, false, options.strict);
+      console.log(chalk.green('\nOpenLAG checks passed.'));
+    } catch {
+      console.error(chalk.red('\nOpenLAG checks failed.'));
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/scripts/cli/vite-bin.ts

@@ -0,0 +1,8 @@
+import path from 'path';
+import { createRequire } from 'module';
+
+export function resolveViteBin(importMetaUrl: string) {
+  const require = createRequire(importMetaUrl);
+  const viteEntry = require.resolve('vite');
+  return path.resolve(path.dirname(viteEntry), '../../bin/vite.js');
+}

package/scripts/core/parser/diagnostic.ts

@@ -0,0 +1,34 @@
+import { ParseError } from "./types.js";
+
+export enum Severity {
+    CRITICAL = 'CRITICAL',
+    INVALID = 'INVALID',
+    DEGRADED = 'DEGRADED',
+    WARNING = 'WARNING'
+}
+
+export interface Diagnostic {
+    file: string;
+    message: string;
+    severity: Severity;
+}
+
+export class DiagnosticEngine {
+    private diagnostics: Diagnostic[] = [];
+
+    add(file: string, message: string, severity: Severity) {
+        this.diagnostics.push({ file, message, severity });
+    }
+
+    getDiagnostics(): Diagnostic[] {
+        return this.diagnostics;
+    }
+
+    getErrors(): ParseError[] {
+        return this.diagnostics.map(d => ({ file: d.file, message: `[${d.severity}] ${d.message}` }));
+    }
+    
+    hasCritical(): boolean {
+        return this.diagnostics.some(d => d.severity === Severity.CRITICAL);
+    }
+}

package/scripts/core/parser/normalizer.ts

@@ -0,0 +1,27 @@
+import { ArtifactType } from "../../../src/types.js";
+import { inferLayer } from "../../../src/core/semantic/artifact-layers.js";
+
+export function normalizeArtifact(parsed: any, fullPath: string, body: string): any {
+  const p = {...parsed};
+  if (!p.schemaVersion) {
+      p.schemaVersion = '1.0.0'; // Assign legacy version
+  }
+
+  const typeValue = (p.type || p.Type) as ArtifactType;
+  return {
+    id: String(p.id || p.ID || ''),
+    type: typeValue,
+    subType: p.subType || p.subtype || p.SubType,
+    title: String(p.title || p.Title || (p.id || p.ID || '')),
+    version: String(p.version || p.Version || 'v-1'),
+    description: body,
+    systemVersionId: p.systemVersionId || p.systemversionid,
+    component: p.component,
+    releaseDate: p.releaseDate || p.timestamp,
+    status: p.status,
+    layer: inferLayer(typeValue),
+    ownership: p.ownership || p.owner ? { owner: p.owner, ...p.ownership } : undefined,
+    file: fullPath,
+    schemaVersion: p.schemaVersion
+  };
+}

package/scripts/core/parser/scanner.ts

@@ -0,0 +1,30 @@
+
+import fs from "fs";
+import path from "path";
+import { RawDocument } from "./types.js";
+
+export function scanDocs(docsDir: string): RawDocument[] {
+    const documents: RawDocument[] = [];
+
+    const traverse = (dir: string) => {
+        if (!fs.existsSync(dir)) return;
+        const items = fs.readdirSync(dir);
+        for (const item of items) {
+            const fullPath = path.join(dir, item);
+            const stat = fs.statSync(fullPath);
+
+            if (stat.isDirectory()) {
+                traverse(fullPath);
+            } else if (item.endsWith('.md')) {
+                const content = fs.readFileSync(fullPath, 'utf-8');
+                documents.push({
+                    file: fullPath,
+                    content
+                });
+            }
+        }
+    };
+
+    traverse(docsDir);
+    return documents;
+}

package/scripts/core/parser/schemas.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+
+export const ArtifactSchema = z.object({
+  id: z.string(),
+  type: z.string(),
+  subType: z.string().optional(),
+  title: z.string(),
+  version: z.string(),
+  description: z.string(),
+  systemVersionId: z.string().optional(),
+  status: z.enum(['draft', 'in_progress', 'ready', 'closed', 'deprecated']).optional(),
+  layer: z.string().optional(),
+  ownership: z.object({
+    owner: z.string().optional(),
+    team: z.string().optional(),
+    domain: z.string().optional(),
+    maintainers: z.array(z.string()).optional(),
+    reviewers: z.array(z.string()).optional(),
+    steward: z.string().optional(),
+  }).optional(),
+  file: z.string(),
+  schemaVersion: z.string().optional(),
+});

package/scripts/core/parser/types.ts

@@ -0,0 +1,30 @@
+import { Artifact, ArtifactType, Relation, RelationType, Change, ChangeType, SystemVersion, Version } from "../../../src/types.js";
+
+export interface ParsedArtifact extends Artifact {
+  file: string;
+  status?: 'draft' | 'in_progress' | 'ready' | 'closed' | 'deprecated';
+}
+
+export interface ParsedRelation extends Relation {
+  file: string;
+}
+
+export interface ParseError {
+  file: string;
+  message: string;
+}
+
+export interface OpenLagData {
+  versions: Version[];
+  systemVersions: SystemVersion[];
+  changes: Change[];
+  artifacts: ParsedArtifact[];
+  relations: ParsedRelation[];
+  errors: ParseError[];
+}
+
+export interface RawDocument {
+  file: string;
+  content: string;
+  frontmatter?: Record<string, any>;
+}

package/scripts/core/parser.ts

@@ -0,0 +1,127 @@
+import { scanDocs } from "./parser/scanner.js";
+import { ParsedArtifact, ParsedRelation, ParseError, OpenLagData, RawDocument } from "./parser/types.js";
+export type { ParsedArtifact, ParsedRelation, ParseError, OpenLagData, RawDocument };
+import { ArtifactType } from "../../src/types.js";
+import { ArtifactSchema } from "./parser/schemas.js";
+import { normalizeArtifact } from "./parser/normalizer.js";
+import { DiagnosticEngine, Severity } from "./parser/diagnostic.js";
+import { RelationRegistry } from "../../src/core/registry/RelationRegistry.js";
+import yaml from "js-yaml";
+
+export function parseOpenLagDocs(docsDir: string): OpenLagData {
+  const diag = new DiagnosticEngine();
+  const state: OpenLagData = {
+    versions: [],
+    systemVersions: [],
+    changes: [],
+    artifacts: [],
+    relations: [],
+    errors: []
+  };
+
+  const documents = scanDocs(docsDir);
+
+  for (const doc of documents) {
+    const { content, file: fullPath } = doc;
+    const sections = content.split(/---+\r?\n/);
+    
+    let i = 0;
+    if (content.trim().startsWith('---')) i = 1;
+
+    for (; i < sections.length; i += 1) {
+          const section = sections[i].trim();
+          if (section.length < 5) continue;
+
+          let parsed: any;
+          try {
+            const yamlCandidate = sections[i].split('\n')
+              .map(l => l.replace(/^##\s?/, ''))
+              .join('\n')
+              .replace(/---$/, '')
+              .trim();
+            
+            parsed = yaml.load(yamlCandidate) as any;
+          } catch (e) {
+            throw new Error(`CRITICAL: Invalid YAML block in ${fullPath}: ${(e as Error).message}`, { cause: e });
+          }
+
+          if (parsed && typeof parsed === 'object' && (parsed.id || parsed.ID) && (parsed.type || parsed.Type)) {
+            const body = (i + 1 < sections.length) ? sections[i+1].trim() : '';
+            if (i+1 < sections.length) i++; // Consume body section if we took it
+
+            const normalized = normalizeArtifact(parsed, fullPath, body);
+            
+            try {
+              ArtifactSchema.parse(normalized);
+              
+              const artifact: ParsedArtifact = normalized;
+              state.artifacts.push(artifact);
+
+              const typeValue = artifact.type as ArtifactType;
+
+              if (typeValue === 'VERSION') {
+                state.versions.push({
+                  id: artifact.id,
+                  name: String(parsed.name || ''),
+                  timestamp: String(parsed.timestamp || ''),
+                  parentVersion: parsed.parentVersion || null
+                });
+              } else if (typeValue === 'SYSTEM_VERSION') {
+                state.systemVersions.push({
+                  id: artifact.id,
+                  component: String(parsed.component || ''),
+                  version: String(parsed.version || ''),
+                  releaseDate: String(parsed.releaseDate || '')
+                });
+              } else if (typeValue === 'CHANGE') {
+                state.changes.push({
+                  id: artifact.id,
+                  type: parsed.changeType || 'FEATURE',
+                  title: artifact.title,
+                  description: artifact.description,
+                  affects: Array.isArray(parsed.affects) ? parsed.affects : [],
+                  versionFrom: String(parsed.versionFrom || ''),
+                  versionTo: String(parsed.versionTo || '')
+                });
+              }
+
+              const rels = parsed.relations || parsed.Relations;
+              if (rels) {
+                const relArray = Array.isArray(rels) ? rels : [rels];
+                relArray.forEach((rel: any, idx: number) => {
+                  const to = typeof rel === 'string' ? rel : (rel.to || rel.id || rel.ID);
+                  if (to) {
+                     const relType = rel.type;
+                     if (!relType) {
+                         diag.add(fullPath, `Relation targeting ${to} missing 'type' in artifact ${artifact.id}`, Severity.WARNING);
+                         return; // Skip inference, strictly require type
+                     }
+                     const contract = RelationRegistry.getContract(relType);
+                     state.relations.push({
+                        id: `rel-${artifact.id}-${idx}`,
+                        from: artifact.id,
+                        to: String(to),
+                        type: relType,
+                        category: contract?.category,
+                        strength: contract?.strength,
+                        file: fullPath
+                     });
+                  }
+                });
+              }
+            } catch (e) {
+                diag.add(fullPath, `Schema validation error: ${(e as Error).message}`, Severity.INVALID);
+            }
+
+          } else if (parsed && typeof parsed === 'object') {
+            if (!(parsed.id || parsed.ID)) {
+                diag.add(fullPath, `Missing ID in artifact`, Severity.INVALID);
+            } else if (!(parsed.type || parsed.Type)) {
+                diag.add(fullPath, `Missing Type in artifact`, Severity.INVALID);
+            }
+          }
+        }
+      }
+  state.errors = diag.getErrors();
+  return state;
+}

package/scripts/generate-relations.ts

@@ -0,0 +1,53 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+
+const relationsDir = path.join(process.cwd(), 'docs/relations');
+const outputFile = path.join(process.cwd(), 'src/core/generated/relation-definitions.ts');
+
+const files = fs.readdirSync(relationsDir);
+const relations: any[] = [];
+
+files.forEach(file => {
+  if (file.endsWith('.yaml')) {
+    const content = fs.readFileSync(path.join(relationsDir, file), 'utf-8');
+    const parsed = yaml.load(content) as any;
+    relations.push({
+      type: parsed.relation,
+      description: parsed.description,
+      category: parsed.category,
+      allowedFrom: parsed.allowedFrom || [],
+      allowedTo: parsed.allowedTo || [],
+      multiplicity: parsed.multiplicity || { from: 'many', to: 'many' },
+      validation: parsed.validation || { severity: 'error' },
+      strength: parsed.validation?.severity === 'error' ? 'STRONG' : (parsed.validation?.severity === 'warn' ? 'MEDIUM' : 'WEAK')
+    });
+  }
+});
+
+const fileContent = `
+// GENERATED FILE - DO NOT EDIT MANUALLY
+import { RelationCategory, RelationStrength } from '../../types.js';
+import { ArtifactType } from '../registry/ArtifactRegistry.js';
+
+export interface RelationContract {
+  type: string;
+  description?: string;
+  category: RelationCategory;
+  strength: RelationStrength;
+  allowedFrom: ArtifactType[];
+  allowedTo: ArtifactType[];
+  multiplicity: { from: string; to: string };
+  validation: { severity: string };
+}
+
+export const GENERATED_RELATIONS: RelationContract[] = ${JSON.stringify(relations, null, 2)};
+`;
+
+if (!fs.existsSync(path.dirname(outputFile))) {
+    fs.mkdirSync(path.dirname(outputFile), { recursive: true });
+}
+
+fs.writeFileSync(outputFile, fileContent);
+console.log('Relation definitions generated.');
+

package/scripts/lint/lint-engine.ts

@@ -0,0 +1,85 @@
+import fs from "fs";
+import path from "path";
+import yaml from "js-yaml";
+import chalk from 'chalk';
+import { parseOpenLagDocs } from "../core/parser.js";
+import { runLintRules } from "./lint-rules.js";
+import { defaultProfiles } from "./lint-profiles.js";
+import { LintConfig, LintReport, LintIssue, LintSummary } from "./lint-types.js";
+
+export function loadConfig(configPath: string): LintConfig {
+  const defaultConfig: LintConfig = {
+    defaultProfile: 'develop',
+    failOnWarnings: false,
+    profiles: {}
+  };
+
+  if (fs.existsSync(configPath)) {
+    try {
+      const fileContent = fs.readFileSync(configPath, 'utf8');
+      const parsed = yaml.load(fileContent) as any;
+      if (parsed && parsed.lint) {
+        return {
+          ...defaultConfig,
+          ...parsed.lint
+        };
+      }
+    } catch (e) {
+      console.warn("⚠️  Could not parse openlag.config.yml, using defaults.");
+    }
+  }
+
+  return defaultConfig;
+}
+
+export function runLint(docsDir: string, configPath: string, profileName?: string): LintReport {
+  const config = loadConfig(configPath);
+  const selectedProfileName = profileName || config.defaultProfile;
+  
+  const baseProfile = defaultProfiles[selectedProfileName] || defaultProfiles['develop'];
+  const customProfileOverrides = config.profiles[selectedProfileName] || {};
+  
+  const activeProfile = { ...baseProfile, ...customProfileOverrides };
+
+  const parsedData = parseOpenLagDocs(docsDir);
+  const issues = runLintRules(parsedData, activeProfile);
+
+  const summary: LintSummary = {
+     errors: 0,
+     warnings: 0,
+     info: 0
+  };
+
+  for (const issue of issues) {
+     if (issue.severity === 'error') summary.errors++;
+     if (issue.severity === 'warning') summary.warnings++;
+     if (issue.severity === 'info') summary.info++;
+  }
+
+  return {
+    profile: selectedProfileName,
+    summary,
+    issues
+  };
+}
+
+export function printHumanReport(report: LintReport) {
+  console.log(`\n` + chalk.bold(`OpenLAG Lint Report`));
+  console.log(chalk.dim(`Profile: ${report.profile}\n`));
+
+  if (report.issues.length === 0) {
+      console.log(chalk.green(`✅ No issues found!\n`));
+  } else {
+      for (const issue of report.issues) {
+          const sevColor = issue.severity === 'error' ? chalk.red : (issue.severity === 'warning' ? chalk.yellow : chalk.cyan);
+          const severityLabel = issue.severity.toUpperCase().padEnd(7);
+          const ruleLabel = issue.rule.padEnd(30);
+          console.log(`${sevColor(severityLabel)} ${chalk.dim(ruleLabel)} ${issue.message}`);
+      }
+  }
+
+  console.log(`\n` + chalk.bold(`Summary:`));
+  console.log(chalk.red(`Errors:   ${report.summary.errors}`));
+  console.log(chalk.yellow(`Warnings: ${report.summary.warnings}`));
+  console.log(chalk.cyan(`Info:     ${report.summary.info}\n`));
+}

package/scripts/lint/lint-profiles.ts

@@ -0,0 +1,49 @@
+import { LintProfile } from './lint-types.js';
+
+export const defaultProfiles: Record<string, LintProfile> = {
+  feature: {
+    duplicateId: 'error',
+    invalidYaml: 'error',
+    brokenRelation: 'error',
+    missingRequiredFields: 'warning',
+    requirementWithoutImplementation: 'info',
+    requirementWithoutTest: 'info',
+    codeWithoutRequirement: 'info',
+    closedArtifactWithPendingRelations: 'warning',
+    orphanArtifact: 'info',
+    invalidRelationType: 'error',
+    invalidArtifactType: 'error',
+    invalidLayerRelation: 'info',
+    missingOwnership: 'info',
+  },
+  develop: {
+    duplicateId: 'error',
+    invalidYaml: 'error',
+    brokenRelation: 'error',
+    missingRequiredFields: 'error',
+    requirementWithoutImplementation: 'warning',
+    requirementWithoutTest: 'warning',
+    codeWithoutRequirement: 'warning',
+    closedArtifactWithPendingRelations: 'warning',
+    orphanArtifact: 'warning',
+    invalidRelationType: 'error',
+    invalidArtifactType: 'error',
+    invalidLayerRelation: 'warning',
+    missingOwnership: 'warning',
+  },
+  release: {
+    duplicateId: 'error',
+    invalidYaml: 'error',
+    brokenRelation: 'error',
+    missingRequiredFields: 'error',
+    requirementWithoutImplementation: 'error',
+    requirementWithoutTest: 'error',
+    codeWithoutRequirement: 'error',
+    closedArtifactWithPendingRelations: 'error',
+    orphanArtifact: 'error',
+    invalidRelationType: 'error',
+    invalidArtifactType: 'error',
+    invalidLayerRelation: 'error',
+    missingOwnership: 'error',
+  }
+};