@juangcarmona/lighthouse 0.6.0 → 0.7.0

package/assets/schemas/profile-catalog.schema.json

@@ -4,59 +4,325 @@
   "title": "Lighthouse profile catalog",
   "type": "object",
   "additionalProperties": false,
-  "required": ["$schema", "schemaVersion", "profiles"],
+  "required": [
+    "$schema",
+    "schemaVersion",
+    "profiles"
+  ],
   "properties": {
-    "$schema": { "type": "string" },
-    "schemaVersion": { "const": 1 },
+    "$schema": {
+      "type": "string"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
     "profiles": {
       "type": "array",
-      "items": { "$ref": "#/$defs/profile" }
+      "items": {
+        "$ref": "#/$defs/profile"
+      }
     }
   },
   "$defs": {
     "profile": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["id", "owner", "purpose", "appliesTo", "surfaces", "verification"],
+      "required": [
+        "id",
+        "owner",
+        "purpose",
+        "appliesTo",
+        "surfaces",
+        "prerequisites",
+        "dependencies",
+        "incompatibleWith",
+        "libraries",
+        "structure",
+        "commands",
+        "guardrails",
+        "failureConsequence",
+        "repairHints",
+        "exceptions",
+        "combinations",
+        "consumerFixture",
+        "upgradeStrategy",
+        "verification"
+      ],
       "properties": {
-        "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
-        "owner": { "type": "string", "minLength": 1 },
-        "purpose": { "type": "string", "minLength": 1 },
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+        },
+        "owner": {
+          "type": "string",
+          "minLength": 1
+        },
+        "purpose": {
+          "type": "string",
+          "minLength": 1
+        },
         "appliesTo": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["shapes", "stacks"],
+          "required": [
+            "shapes",
+            "stacks"
+          ],
           "properties": {
-            "shapes": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true },
-            "stacks": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+            "shapes": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "minItems": 1,
+              "uniqueItems": true
+            },
+            "stacks": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "uniqueItems": true
+            }
           }
         },
-        "surfaces": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "uniqueItems": true },
+        "surfaces": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
         "verification": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["layers"],
+          "required": [
+            "layers"
+          ],
           "properties": {
             "layers": {
               "type": "array",
-              "items": { "$ref": "#/$defs/layer" },
+              "items": {
+                "$ref": "#/$defs/layer"
+              },
               "minItems": 1,
               "uniqueItems": true
             }
           }
+        },
+        "prerequisites": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "dependencies": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/profileId"
+          },
+          "uniqueItems": true
+        },
+        "incompatibleWith": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/profileId"
+          },
+          "uniqueItems": true
+        },
+        "libraries": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "structure": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "commands": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "guardrails": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/guardrail"
+          },
+          "uniqueItems": true
+        },
+        "failureConsequence": {
+          "type": "string",
+          "minLength": 1
+        },
+        "repairHints": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 1
+        },
+        "exceptions": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 1
+        },
+        "combinations": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/combination"
+          },
+          "uniqueItems": true
+        },
+        "consumerFixture": {
+          "type": "string",
+          "minLength": 1
+        },
+        "upgradeStrategy": {
+          "type": "string",
+          "minLength": 1
         }
       }
     },
     "layer": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["id", "level", "kind", "verification"],
+      "required": [
+        "id",
+        "level",
+        "kind",
+        "verification"
+      ],
       "properties": {
-        "id": { "enum": ["static", "unit", "architecture", "integration", "functional", "browser-e2e", "operational"] },
-        "level": { "enum": ["required", "recommended", "optional"] },
-        "kind": { "enum": ["hard", "soft"] },
-        "verification": { "enum": ["deterministic", "semantic", "human"] },
-        "command": { "type": ["string", "null"] }
+        "id": {
+          "enum": [
+            "static",
+            "unit",
+            "architecture",
+            "integration",
+            "functional",
+            "browser-e2e",
+            "operational"
+          ]
+        },
+        "level": {
+          "enum": [
+            "required",
+            "recommended",
+            "optional"
+          ]
+        },
+        "kind": {
+          "enum": [
+            "hard",
+            "soft"
+          ]
+        },
+        "verification": {
+          "enum": [
+            "deterministic",
+            "semantic",
+            "human"
+          ]
+        },
+        "command": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "profileId": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "guardrail": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "level",
+        "kind",
+        "verification",
+        "command",
+        "description"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "level": {
+          "enum": [
+            "required",
+            "recommended",
+            "optional"
+          ]
+        },
+        "kind": {
+          "enum": [
+            "hard",
+            "soft"
+          ]
+        },
+        "verification": {
+          "enum": [
+            "deterministic",
+            "semantic",
+            "human"
+          ]
+        },
+        "command": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "combination": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "with",
+        "purpose"
+      ],
+      "properties": {
+        "with": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/profileId"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "purpose": {
+          "type": "string",
+          "minLength": 1
+        }
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Lighthouse adoption and verification CLI",
   "repository": {

package/src/lighthouse.mjs

@@ -46,10 +46,15 @@ const managedPaths = [
 const profileManagedPaths = Object.freeze({
   'visual-theme': ['docs/design/DESIGN.md', '.agents/skills/lighthouse-ui/SKILL.md'],
   'dotnet-backend': ['docs/profiles/dotnet/README.md', 'docs/profiles/dotnet/adoption.md', 'docs/profiles/dotnet/architecture.md', 'docs/profiles/dotnet/guardrails.md', 'docs/profiles/dotnet/practices.md', 'docs/profiles/dotnet/testing-and-development.md', 'docs/profiles/dotnet/use-cases.md', '.agents/skills/lighthouse-dotnet/SKILL.md'],
+  'react-web-platform': ['docs/profiles/react-web-platform/README.md', 'docs/profiles/react-web-platform/adoption.md', 'docs/profiles/react-web-platform/structure.md', 'docs/profiles/react-web-platform/guardrails.md', 'docs/profiles/react-web-platform/testing.md', '.agents/skills/lighthouse-react-web/SKILL.md'],
+  'web-bff': ['docs/profiles/web-bff/README.md', 'docs/profiles/web-bff/adoption.md', 'docs/profiles/web-bff/security.md', 'docs/profiles/web-bff/testing.md', '.agents/skills/lighthouse-web-bff/SKILL.md'],
+  'pwa-capability': ['docs/profiles/pwa-capability/README.md', 'docs/profiles/pwa-capability/adoption.md', 'docs/profiles/pwa-capability/guardrails.md', 'docs/profiles/pwa-capability/offline.md', 'docs/profiles/pwa-capability/testing.md', '.agents/skills/lighthouse-pwa/SKILL.md'],
+  'mobile-expo': ['docs/profiles/mobile-expo/README.md', 'docs/profiles/mobile-expo/adoption.md', 'docs/profiles/mobile-expo/guardrails.md', 'docs/profiles/mobile-expo/testing.md', '.agents/skills/lighthouse-mobile-expo/SKILL.md'],
+  'mobile-maui': ['docs/profiles/mobile-maui/README.md', 'docs/profiles/mobile-maui/adoption.md', 'docs/profiles/mobile-maui/guardrails.md', 'docs/profiles/mobile-maui/testing.md', '.agents/skills/lighthouse-mobile-maui/SKILL.md'],
 });
 const previousManagedPaths = managedPaths.slice(0, -1);
 const legacyManagedPaths = [projection];
-const supportedProfiles = ['node-tooling', 'dotnet-backend', 'visual-theme'];
+const supportedProfiles = readProfileCatalog().profiles.map(({ id }) => id);
 const branchPattern = '^(feat|fix|docs|refactor|test|chore|build|ci|perf|revert)/[1-9]\\d*-[a-z0-9]+(?:-[a-z0-9]+)*$';
 const authorityVersions = { productShape: '0.22.0', arcShape: '0.1.3' };
 const upgradeSchema = './node_modules/@juangcarmona/lighthouse/assets/schemas/lighthouse-upgrade.schema.json';
@@ -96,6 +101,46 @@ function profileAssets(manifest) {
       catch (error) { throw new Error(`Cannot read the installed Lighthouse .NET profile: ${error.message}`); }
     }
   }
+  if ((manifest?.profiles ?? []).includes('react-web-platform')) {
+    const files = ['README.md', 'adoption.md', 'structure.md', 'guardrails.md', 'testing.md', 'SKILL.md'];
+    for (const file of files) {
+      const target = file === 'SKILL.md' ? '.agents/skills/lighthouse-react-web/SKILL.md' : `docs/profiles/react-web-platform/${file}`;
+      try { assets[target] = readFileSync(new URL(`../assets/profiles/react-web-platform/${file}`, import.meta.url), 'utf8'); }
+      catch (error) { throw new Error(`Cannot read the installed Lighthouse React web profile: ${error.message}`); }
+    }
+  }
+  if ((manifest?.profiles ?? []).includes('web-bff')) {
+    const files = ['README.md', 'adoption.md', 'security.md', 'testing.md', 'SKILL.md'];
+    for (const file of files) {
+      const target = file === 'SKILL.md' ? '.agents/skills/lighthouse-web-bff/SKILL.md' : `docs/profiles/web-bff/${file}`;
+      try { assets[target] = readFileSync(new URL(`../assets/profiles/web-bff/${file}`, import.meta.url), 'utf8'); }
+      catch (error) { throw new Error(`Cannot read the installed Lighthouse web BFF profile: ${error.message}`); }
+    }
+  }
+  if ((manifest?.profiles ?? []).includes('pwa-capability')) {
+    const files = ['README.md', 'adoption.md', 'guardrails.md', 'offline.md', 'testing.md', 'SKILL.md'];
+    for (const file of files) {
+      const target = file === 'SKILL.md' ? '.agents/skills/lighthouse-pwa/SKILL.md' : `docs/profiles/pwa-capability/${file}`;
+      try { assets[target] = readFileSync(new URL(`../assets/profiles/pwa-capability/${file}`, import.meta.url), 'utf8'); }
+      catch (error) { throw new Error(`Cannot read the installed Lighthouse PWA capability: ${error.message}`); }
+    }
+  }
+  if ((manifest?.profiles ?? []).includes('mobile-expo')) {
+    const files = ['README.md', 'adoption.md', 'guardrails.md', 'testing.md', 'SKILL.md'];
+    for (const file of files) {
+      const target = file === 'SKILL.md' ? '.agents/skills/lighthouse-mobile-expo/SKILL.md' : `docs/profiles/mobile-expo/${file}`;
+      try { assets[target] = readFileSync(new URL(`../assets/profiles/mobile-expo/${file}`, import.meta.url), 'utf8'); }
+      catch (error) { throw new Error(`Cannot read the installed Lighthouse Expo mobile profile: ${error.message}`); }
+    }
+  }
+  if ((manifest?.profiles ?? []).includes('mobile-maui')) {
+    const files = ['README.md', 'adoption.md', 'guardrails.md', 'testing.md', 'SKILL.md'];
+    for (const file of files) {
+      const target = file === 'SKILL.md' ? '.agents/skills/lighthouse-mobile-maui/SKILL.md' : `docs/profiles/mobile-maui/${file}`;
+      try { assets[target] = readFileSync(new URL(`../assets/profiles/mobile-maui/${file}`, import.meta.url), 'utf8'); }
+      catch (error) { throw new Error(`Cannot read the installed Lighthouse .NET MAUI mobile profile: ${error.message}`); }
+    }
+  }
   return assets;
 }
 

package/src/profiles.mjs

@@ -7,12 +7,37 @@ const allowedLevels = new Set(['required', 'recommended', 'optional']);
 const allowedKinds = new Set(['hard', 'soft']);
 const allowedVerification = new Set(['deterministic', 'semantic', 'human']);
 const allowedLayers = new Set(['static', 'unit', 'architecture', 'integration', 'functional', 'browser-e2e', 'operational']);
+const profileIdPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+
+function stringArrayProblems(value, name, { required = false } = {}) {
+  if (!Array.isArray(value) || (required && value.length === 0) || value.some((item) => typeof item !== 'string' || !item)) {
+    return [`${name} must contain strings`];
+  }
+  return new Set(value).size === value.length ? [] : [`${name} must be unique`];
+}
+
+function profileReferenceProblems(value, name) {
+  return stringArrayProblems(value, name).concat((value ?? []).filter((id) => !profileIdPattern.test(id)).map((id) => `${name} contains invalid profile id ${id}`));
+}
+
+function guardrailProblems(guardrail) {
+  if (!guardrail || typeof guardrail !== 'object' || Array.isArray(guardrail)) return ['guardrail must be an object'];
+  const problems = [];
+  for (const key of ['id', 'level', 'kind', 'verification', 'command', 'description']) if (!(key in guardrail)) problems.push(`guardrail missing ${key}`);
+  if (typeof guardrail.id !== 'string' || !guardrail.id) problems.push('guardrail id must be a non-empty string');
+  if (!allowedLevels.has(guardrail.level)) problems.push(`guardrail ${guardrail.id} has an invalid level`);
+  if (!allowedKinds.has(guardrail.kind)) problems.push(`guardrail ${guardrail.id} has an invalid kind`);
+  if (!allowedVerification.has(guardrail.verification)) problems.push(`guardrail ${guardrail.id} has an invalid verification method`);
+  if (guardrail.command !== null && (typeof guardrail.command !== 'string' || !guardrail.command)) problems.push(`guardrail ${guardrail.id} command must be a string or null`);
+  if (typeof guardrail.description !== 'string' || !guardrail.description) problems.push(`guardrail ${guardrail.id} description must be a non-empty string`);
+  return problems;
+}
 
 function profileProblems(profile) {
   const problems = [];
   if (!profile || typeof profile !== 'object' || Array.isArray(profile)) return ['profile must be an object'];
   for (const key of ['id', 'owner', 'purpose', 'appliesTo', 'surfaces', 'verification']) if (!(key in profile)) problems.push(`missing ${key}`);
-  if (typeof profile.id !== 'string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(profile.id)) problems.push('id must use kebab-case');
+  if (typeof profile.id !== 'string' || !profileIdPattern.test(profile.id)) problems.push('id must use kebab-case');
   if (typeof profile.owner !== 'string' || !profile.owner) problems.push('owner must be a non-empty string');
   if (typeof profile.purpose !== 'string' || !profile.purpose) problems.push('purpose must be a non-empty string');
   const applicability = profile.appliesTo;
@@ -24,6 +49,24 @@ function profileProblems(profile) {
   if (Array.isArray(applicability?.shapes) && new Set(applicability.shapes).size !== applicability.shapes.length) problems.push('appliesTo.shapes must be unique');
   if (Array.isArray(applicability?.stacks) && (applicability.stacks.some((stack) => typeof stack !== 'string') || new Set(applicability.stacks).size !== applicability.stacks.length)) problems.push('appliesTo.stacks must contain unique strings');
   if (!Array.isArray(profile.surfaces) || profile.surfaces.length === 0 || profile.surfaces.some((surface) => typeof surface !== 'string' || !surface)) problems.push('surfaces must contain non-empty strings');
+  for (const [name, value] of [['prerequisites', profile.prerequisites], ['libraries', profile.libraries], ['structure', profile.structure], ['commands', profile.commands], ['repairHints', profile.repairHints], ['exceptions', profile.exceptions]]) problems.push(...stringArrayProblems(value, name, { required: ['repairHints', 'exceptions'].includes(name)}));
+  for (const [name, value] of [['dependencies', profile.dependencies], ['incompatibleWith', profile.incompatibleWith]]) problems.push(...profileReferenceProblems(value, name));
+  if (typeof profile.failureConsequence !== 'string' || !profile.failureConsequence) problems.push('failureConsequence must be a non-empty string');
+  if (typeof profile.consumerFixture !== 'string' || !profile.consumerFixture) problems.push('consumerFixture must be a non-empty string');
+  if (typeof profile.upgradeStrategy !== 'string' || !profile.upgradeStrategy) problems.push('upgradeStrategy must be a non-empty string');
+  if (!Array.isArray(profile.guardrails) || profile.guardrails.length === 0) problems.push('guardrails must contain at least one guardrail');
+  const guardrailIds = new Set();
+  for (const guardrail of profile.guardrails ?? []) {
+    problems.push(...guardrailProblems(guardrail));
+    if (guardrail?.id && guardrailIds.has(guardrail.id)) problems.push(`duplicate guardrail ${guardrail.id}`);
+    if (guardrail?.id) guardrailIds.add(guardrail.id);
+  }
+  if (!Array.isArray(profile.combinations)) problems.push('combinations must be an array');
+  for (const combination of profile.combinations ?? []) {
+    if (!combination || typeof combination !== 'object' || Array.isArray(combination)) { problems.push('combination must be an object'); continue; }
+    if (!Array.isArray(combination.with) || combination.with.length === 0 || combination.with.some((id) => typeof id !== 'string' || !profileIdPattern.test(id))) problems.push('combination.with must contain profile ids');
+    if (typeof combination.purpose !== 'string' || !combination.purpose) problems.push('combination.purpose must be a non-empty string');
+  }
   const layers = profile.verification?.layers;
   if (!Array.isArray(layers) || layers.length === 0) problems.push('verification.layers must contain at least one layer');
   const ids = new Set();
@@ -52,6 +95,11 @@ function catalogProblems(catalog) {
     if (profile?.id && ids.has(profile.id)) problems.push(`${profile.id}: duplicate id`);
     if (profile?.id) ids.add(profile.id);
   }
+  for (const profile of catalog.profiles ?? []) {
+    for (const reference of [...(profile.dependencies ?? []), ...(profile.incompatibleWith ?? []), ...(profile.combinations ?? []).flatMap((combination) => combination.with ?? [])]) {
+      if (!ids.has(reference)) problems.push(`${profile.id}: references undeclared profile ${reference}`);
+    }
+  }
   return problems;
 }
 
@@ -80,31 +128,56 @@ function profileStatus(profile, application) {
   return 'passed';
 }
 
+function profileCompositionProblems(profile, selectedIds) {
+  const problems = [];
+  for (const dependency of profile.dependencies ?? []) if (!selectedIds.has(dependency)) problems.push(`${profile.id} requires the ${dependency} profile.`);
+  for (const incompatible of profile.incompatibleWith ?? []) if (selectedIds.has(incompatible)) problems.push(`${profile.id} is incompatible with the ${incompatible} profile.`);
+  return problems;
+}
+
 export function composeProfiles(catalog, manifest) {
   const application = normalizeApplication(manifest?.application);
+  const selectedIds = new Set(manifest?.profiles ?? []);
   const selected = (manifest?.profiles ?? []).map((id) => {
     const profile = catalog.profiles.find((item) => item.id === id);
     const status = profile ? profileStatus(profile, application) : 'failed';
+    const compositionProblems = profile ? profileCompositionProblems(profile, selectedIds) : [];
     const problems = profile
       ? status === 'failed'
         ? [`${id} does not apply to application shape '${application.shape}' and stacks '${application.stacks.join(', ') || 'none'}'.`]
         : status === 'unconfigured'
           ? [`${id} needs application.shape and${profile.appliesTo.stacks.length ? ' application.stacks' : ''} in lighthouse.json.`]
-          : []
+          : compositionProblems
       : [`${id} is not declared by the installed profile catalog.`];
+    const effectiveStatus = status === 'failed' || compositionProblems.length ? 'failed' : status;
     return {
       id,
       owner: profile?.owner ?? '@juangcarmona/lighthouse',
       purpose: profile?.purpose ?? null,
-      status,
       appliesTo: profile?.appliesTo ?? null,
       surfaces: profile?.surfaces ?? [],
+      prerequisites: profile?.prerequisites ?? [],
+      dependencies: profile?.dependencies ?? [],
+      incompatibleWith: profile?.incompatibleWith ?? [],
+      libraries: profile?.libraries ?? [],
+      structure: profile?.structure ?? [],
+      commands: profile?.commands ?? [],
+      guardrails: profile?.guardrails ?? [],
+      failureConsequence: profile?.failureConsequence ?? null,
+      repairHints: profile?.repairHints ?? [],
+      exceptions: profile?.exceptions ?? [],
+      combinations: profile?.combinations ?? [],
+      consumerFixture: profile?.consumerFixture ?? null,
+      upgradeStrategy: profile?.upgradeStrategy ?? null,
       verification: profile?.verification ?? { layers: [] },
       problems,
+      status: effectiveStatus,
       nextAction: problems.length
         ? status === 'unconfigured'
           ? 'Declare application.shape and application.stacks, then run lighthouse profiles --format json.'
-          : 'Choose a compatible profile or correct application.shape and application.stacks.'
+          : compositionProblems.length
+            ? 'Select the required profiles or remove the incompatible selection, then rerun lighthouse profiles --format json.'
+            : 'Choose a compatible profile or correct application.shape and application.stacks.'
         : null,
     };
   });
@@ -115,7 +188,7 @@ export function composeProfiles(catalog, manifest) {
       : selected.some((profile) => profile.status === 'unconfigured')
         ? 'unconfigured'
         : 'passed';
-  return { schemaVersion: 1, application, selected, available: catalog.profiles.map(({ id, owner, purpose, appliesTo, surfaces, verification }) => ({ id, owner, purpose, appliesTo, surfaces, verification })), status };
+  return { schemaVersion: 1, application, selected, available: catalog.profiles.map((profile) => ({ ...profile })), status };
 }
 
 export function profileCompositionResult(composition) {