mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-09-02 13:48:03 +00:00
feat: add canonical tier catalog with cross-repo drift detection (#1873)
* feat(tier-reconcile): seed tier-catalog with validated inventory Verified current-state catalog (29 entries) with cross-field invariant (tier: internal iff availability: internal). No internal Linear IDs in committed file; publicRoadmapKey slugs used instead. Canonical validator (scripts/website-catalog/canonical-validate.mjs) passes. Refs: SEN-549 * feat(tier-reconcile): add canonical catalog, sync scripts, and CI drift check Add canonical feature catalog (29 entries, no SEN-NNN identifiers) with cross-field invariant (tier:internal iff availability:internal). Sencho-owned scripts: - canonical-validate.mjs: schema + invariant validation - sync-feature-catalog.mjs: builds sanitized public projection - check-website-drift.mjs: checksum-based drift detection - test-drift-detection.mjs: unit tests for drift logic - test-catalog-no-leak.mjs: no prohibited identifiers GitHub Actions catalog-drift.yml: pull_request required check + push safeguard. Refs: SEN-549 * fix(tier-reconcile): correct relative paths in scripts for standalone runs Use fileURLToPath to resolve paths relative to script directory rather than cwd. Fixes PA-01/PA-02 script execution from any directory. Also removes SEN-NNN references from docs/feature-catalog.yaml entries and updates limitation text per audit. * ci(catalog-drift): authenticate the cross-repo website checkout The drift check reads the website repository, which is private, so the ambient workflow token cannot see it and the checkout failed with a not-found error before any validation ran. Mint a GitHub App installation token scoped to that one repository with read-only contents access, matching the pattern the docs sync workflow already uses. Also declare contents: read at the workflow level so the job stops inheriting the repository default token permissions. * fix(catalog-drift): make the drift check able to fail The job reported success no matter what the website repository contained, for two compounding reasons. The root checkout ran after the website checkout. actions/checkout cleans its destination, so it deleted website-checkout before any script ran. Reorder so the root checkout comes first. The verify step then regenerated the snapshot into that directory before comparing against it, so the comparison only ever read back what it had just written, recreating the deleted tree along the way. Drop the sync call and compare against what the website has actually committed. The comparison also trusted the checksum recorded in the snapshot metadata without checking that it described the snapshot file sitting next to it, so a hand-edited or stale snapshot passed beside fresh metadata. Require both to agree. Round out the surrounding tooling: a catalog with no entries array now fails validation instead of reporting zero entries, the unused clone branch no longer calls require from an ES module, and the failure output names the regeneration command, which is now reachable as an npm script. * ci(catalog-drift): check for website-side drift on a daily schedule The path filters only fire on changes inside this repository, so an edited or reverted snapshot in the website repository left the check green while the two were genuinely out of sync. A daily run closes that window without waiting for someone to touch the canonical catalog. * fix(catalog-scripts): check every prohibited key and drop an inert test The leak check listed five prohibited keys but only tested three by hand, so an entry carrying route or service would have reached the public catalog unnoticed. Drive the loop from the list instead. Remove test-drift-detection.mjs. Nothing invoked it, and it asserted against a reimplemented normalizer rather than the drift script it named, so it reported coverage it did not provide.
This commit is contained in:
Anso
@@ -0,0 +1,107 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Sencho tier-reconciliation: canonical catalog validator
|
||||
* Verifies docs/feature-catalog.yaml against the canonical schema and
|
||||
* the required cross-field invariant (tier: internal iff availability: internal).
|
||||
* Exits 0 on valid, exits 1 with diagnostic lines on invalid.
|
||||
*/
|
||||
import yaml from 'js-yaml';
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
|
||||
import { fileURLToPath } from 'url';
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
const CATALOG_FILE = path.resolve(__dirname, '../../docs/feature-catalog.yaml');
|
||||
|
||||
const VALID_TIERS = new Set(['community', 'admiral', 'internal']);
|
||||
const VALID_AVAILABILITY = new Set(['shipped', 'planned', 'internal']);
|
||||
const VALID_CATEGORIES = new Set([
|
||||
'compose-deploy', 'fleet-orchestration', 'security-foundation',
|
||||
'automation-operations', 'recovery', 'identity-access',
|
||||
'governance', 'assurance', 'internal',
|
||||
]);
|
||||
|
||||
const errors = [];
|
||||
|
||||
function error(msg) { errors.push('ERROR: ' + msg); }
|
||||
|
||||
function readCatalog() {
|
||||
const text = fs.readFileSync(CATALOG_FILE, 'utf8');
|
||||
const doc = yaml.load(text, { schema: yaml.CORE_SCHEMA });
|
||||
if (!doc || typeof doc !== 'object') {
|
||||
throw new Error('catalog is not a YAML mapping');
|
||||
}
|
||||
return doc;
|
||||
}
|
||||
|
||||
function main() {
|
||||
const doc = readCatalog();
|
||||
if (!Array.isArray(doc.entries)) {
|
||||
console.error('FAIL: catalog has no entries array.');
|
||||
process.exit(1);
|
||||
}
|
||||
const entries = doc.entries;
|
||||
const ids = new Set();
|
||||
|
||||
for (const [i, entry] of entries.entries()) {
|
||||
const prefix = `entry[${i}].id=${entry?.id ?? '(missing)'}`;
|
||||
|
||||
if (!entry || typeof entry !== 'object') {
|
||||
error(`${prefix}: entry is not an object`);
|
||||
continue;
|
||||
}
|
||||
|
||||
if (!entry.id) error(`${prefix}: missing id`);
|
||||
else if (ids.has(entry.id)) error(`${prefix}: duplicate id "${entry.id}"`);
|
||||
else ids.add(entry.id);
|
||||
|
||||
if (!entry.name) error(`${prefix}: missing name`);
|
||||
if (!VALID_TIERS.has(entry.tier))
|
||||
error(`${prefix}: invalid tier "${entry.tier}"; must be one of community/admiral/internal`);
|
||||
if (!VALID_AVAILABILITY.has(entry.availability))
|
||||
error(`${prefix}: invalid availability "${entry.availability}"; must be one of shipped/planned/internal`);
|
||||
|
||||
// Cross-field invariant: tier: internal iff availability: internal
|
||||
if (entry.tier === 'internal' && entry.availability !== 'internal')
|
||||
error(`${prefix}: tier: internal requires availability: internal`);
|
||||
if (entry.tier !== 'internal' && entry.availability === 'internal')
|
||||
error(`${prefix}: non-internal tier requires non-internal availability`);
|
||||
|
||||
if (entry.availability === 'planned') {
|
||||
if (!entry.publicRoadmapKey) error(`${prefix}: planned entry must have publicRoadmapKey`);
|
||||
}
|
||||
|
||||
if (!VALID_CATEGORIES.has(entry.category))
|
||||
error(`${prefix}: unknown category "${entry.category}"`);
|
||||
|
||||
// Internal-only fields must not leak into committed catalog.
|
||||
// The canonical file IS public, so we enforce: no linear, no evidence with internal identifiers,
|
||||
// no internalNote. Public-name fields only.
|
||||
if (entry.linear) {
|
||||
// Reject any internal Linear identifier in committed file.
|
||||
if (/SEN-[0-9]/.test(String(entry.linear)))
|
||||
error(`${prefix}: committed catalog contains internal Linear identifier in linear field ("${entry.linear}"); use publicRoadmapKey instead`);
|
||||
}
|
||||
// No evidence field allowed in canonical committed file (evidence stays internal).
|
||||
if (entry.evidence)
|
||||
error(`${prefix}: evidence field must not appear in committed canonical catalog (use Linear/non-public record for evidence); got: ${entry.evidence}`);
|
||||
if (entry.internalNote)
|
||||
error(`${prefix}: internalNote field must not appear in committed canonical catalog`);
|
||||
}
|
||||
|
||||
if (errors.length === 0) {
|
||||
console.log(`VALID: catalog has ${entries.length} entries; all invariants pass.`);
|
||||
process.exit(0);
|
||||
} else {
|
||||
for (const msg of errors) console.error(msg);
|
||||
console.error(`FAIL: ${errors.length} error(s) found.`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
try {
|
||||
main();
|
||||
} catch (e) {
|
||||
console.error('FAIL: ' + (e.message || e));
|
||||
process.exit(1);
|
||||
}
|
||||
@@ -0,0 +1,133 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Sencho tier-reconciliation: website drift detector
|
||||
* Compares the current canonical catalog to the website's committed
|
||||
* catalog-snapshot. Drift identity is the normalized content checksum.
|
||||
* Commit SHA is NOT part of drift identity.
|
||||
*
|
||||
* Usage:
|
||||
* node scripts/website-catalog/check-website-drift.mjs --website-dir <path>
|
||||
* node scripts/website-catalog/check-website-drift.mjs --website-ref <git-ref>
|
||||
*/
|
||||
import yaml from 'js-yaml';
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
import { execFileSync } from 'child_process';
|
||||
import os from 'os';
|
||||
import { createHash } from 'crypto';
|
||||
import { fileURLToPath } from 'url';
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
const CANONICAL_FILE = path.resolve(__dirname, '../../docs/feature-catalog.yaml');
|
||||
const PUBLIC_FIELDS = new Set([
|
||||
'id', 'publicName', 'summary', 'description', 'category',
|
||||
'tier', 'availability', 'featured', 'homepageOrder', 'publicRoadmapKey',
|
||||
]);
|
||||
|
||||
function normalizeYaml(obj) {
|
||||
return yaml.dump(obj, { sortKeys: true, lineWidth: -1 });
|
||||
}
|
||||
|
||||
function computeChecksum(content) {
|
||||
return createHash('sha256').update(content).digest('hex');
|
||||
}
|
||||
|
||||
function loadSnapshot(websiteDir) {
|
||||
const snapshotPath = path.join(websiteDir, 'src/data/catalog-snapshot.yaml');
|
||||
if (!fs.existsSync(snapshotPath)) {
|
||||
return null;
|
||||
}
|
||||
const text = fs.readFileSync(snapshotPath, 'utf8');
|
||||
const doc = yaml.load(text, { schema: yaml.CORE_SCHEMA });
|
||||
if (!doc || !Array.isArray(doc.entries)) return null;
|
||||
return { doc, text, snapshotPath };
|
||||
}
|
||||
|
||||
function buildProjection(canonical) {
|
||||
return canonical.entries
|
||||
.filter((e) => e.tier !== 'internal' && e.availability !== 'internal')
|
||||
.map((e) => {
|
||||
const pub = {};
|
||||
for (const key of PUBLIC_FIELDS) {
|
||||
if (key in e) pub[key] = e[key];
|
||||
}
|
||||
return pub;
|
||||
});
|
||||
}
|
||||
|
||||
function main() {
|
||||
const args = process.argv.slice(2);
|
||||
let websiteDir = null;
|
||||
let websiteRef = null;
|
||||
let cleanup = null;
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
if (args[i] === '--website-dir' && args[i + 1]) {
|
||||
websiteDir = args[i + 1]; i++;
|
||||
} else if (args[i] === '--website-ref' && args[i + 1]) {
|
||||
websiteRef = args[i + 1]; i++;
|
||||
}
|
||||
}
|
||||
|
||||
if (websiteRef && !websiteDir) {
|
||||
// Clone to temp dir
|
||||
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sencho-website-'));
|
||||
execFileSync('git', ['clone', '--depth', '1', '--branch', websiteRef,
|
||||
'https://github.com/Studio-Saelix/sencho-website.git', tmp],
|
||||
{ stdio: 'pipe' });
|
||||
websiteDir = tmp;
|
||||
cleanup = tmp;
|
||||
}
|
||||
|
||||
if (!websiteDir) {
|
||||
console.error('ERROR: --website-dir or --website-ref is required');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Read canonical catalog.
|
||||
const canonicalText = fs.readFileSync(CANONICAL_FILE, 'utf8');
|
||||
const canonical = yaml.load(canonicalText, { schema: yaml.CORE_SCHEMA });
|
||||
const projection = buildProjection(canonical);
|
||||
const projectionText = normalizeYaml({ entries: projection });
|
||||
const currentChecksum = computeChecksum(projectionText);
|
||||
|
||||
// Read committed snapshot.
|
||||
const snap = loadSnapshot(websiteDir);
|
||||
if (!snap) {
|
||||
console.error(`FAIL: no catalog-snapshot.yaml at ${path.join(websiteDir, 'src/data/')}`);
|
||||
if (cleanup) fs.rmSync(cleanup, { recursive: true, force: true });
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const metaPath = path.join(websiteDir, 'src/data/catalog-snapshot.meta.json');
|
||||
let committedChecksum = null;
|
||||
if (fs.existsSync(metaPath)) {
|
||||
try {
|
||||
const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
|
||||
committedChecksum = meta.checksum;
|
||||
} catch { /* ignore */ }
|
||||
}
|
||||
|
||||
// Compute checksum of committed snapshot text (the actual file content).
|
||||
const snapChecksum = computeChecksum(snap.text);
|
||||
|
||||
if (cleanup) fs.rmSync(cleanup, { recursive: true, force: true });
|
||||
|
||||
// The snapshot file must match the canonical projection, and the metadata
|
||||
// must describe that same file. Trusting the metadata alone would let a
|
||||
// hand-edited or stale snapshot pass beside a freshly written meta.json.
|
||||
if (currentChecksum === committedChecksum && snapChecksum === committedChecksum) {
|
||||
console.log(`OK: no drift. checksum=${currentChecksum.slice(0, 12)}...`);
|
||||
process.exit(0);
|
||||
} else {
|
||||
console.error('DRIFT DETECTED:');
|
||||
console.error(` current canonical checksum: ${currentChecksum}`);
|
||||
console.error(` committed snapshot checksum: ${committedChecksum ?? '(none)'}`);
|
||||
console.error(` committed file checksum: ${snapChecksum}`);
|
||||
console.error('');
|
||||
console.error('Regenerate the website snapshot and commit src/data/ in the website repo:');
|
||||
console.error(' npm run catalog:sync -- --website-dir <path-to-sencho-website>');
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
@@ -0,0 +1,101 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Sencho tier-reconciliation: sync feature catalog to website
|
||||
* Reads docs/feature-catalog.yaml (canonical, public-safe), builds a sanitized
|
||||
* public projection, and writes it to <website-dir>/src/data/.
|
||||
*
|
||||
* Usage: node scripts/website-catalog/sync-feature-catalog.mjs --website-dir <path>
|
||||
*
|
||||
* The canonical file contains only public-safe identifiers (no SEN-NNN Linear IDs).
|
||||
* The public projection contains only shipped/planned community|admiral entries
|
||||
* with public presentation fields. Internal entries are excluded.
|
||||
*/
|
||||
import yaml from 'js-yaml';
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
import { createHash } from 'crypto';
|
||||
import { fileURLToPath } from 'url';
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
const CANONICAL_FILE = path.resolve(__dirname, '../../docs/feature-catalog.yaml');
|
||||
const SCHEMA_VERSION = '1';
|
||||
const OUTPUT_SNAPSHOT = 'catalog-snapshot.yaml';
|
||||
const OUTPUT_META = 'catalog-snapshot.meta.json';
|
||||
|
||||
// Fields allowed in the public projection.
|
||||
const PUBLIC_FIELDS = new Set([
|
||||
'id', 'publicName', 'summary', 'description', 'category',
|
||||
'tier', 'availability', 'featured', 'homepageOrder', 'publicRoadmapKey',
|
||||
]);
|
||||
|
||||
function normalizeYaml(obj) {
|
||||
return yaml.dump(obj, { sortKeys: true, lineWidth: -1, commentString: '' });
|
||||
}
|
||||
|
||||
function computeChecksum(content) {
|
||||
return createHash('sha256').update(content).digest('hex');
|
||||
}
|
||||
|
||||
function main() {
|
||||
const args = process.argv.slice(2);
|
||||
let websiteDir = null;
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
if (args[i] === '--website-dir' && args[i + 1]) {
|
||||
websiteDir = args[i + 1];
|
||||
i++;
|
||||
} else if (args[i] === '--help') {
|
||||
console.log('Usage: node sync-feature-catalog.mjs --website-dir <path>');
|
||||
process.exit(0);
|
||||
}
|
||||
}
|
||||
|
||||
if (!websiteDir) {
|
||||
console.error('ERROR: --website-dir is required');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Read and parse canonical catalog.
|
||||
const catText = fs.readFileSync(CANONICAL_FILE, 'utf8');
|
||||
const doc = yaml.load(catText, { schema: yaml.CORE_SCHEMA });
|
||||
if (!doc || !Array.isArray(doc.entries)) {
|
||||
console.error('ERROR: canonical catalog is missing entries array');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Build sanitized public projection.
|
||||
const projection = doc.entries
|
||||
.filter((e) => e.tier !== 'internal' && e.availability !== 'internal')
|
||||
.map((e) => {
|
||||
const pub = {};
|
||||
for (const key of PUBLIC_FIELDS) {
|
||||
if (key in e) pub[key] = e[key];
|
||||
}
|
||||
return pub;
|
||||
});
|
||||
|
||||
const projectionText = normalizeYaml({ entries: projection });
|
||||
const checksum = computeChecksum(projectionText);
|
||||
|
||||
// Write snapshot.
|
||||
const outDir = path.join(websiteDir, 'src', 'data');
|
||||
if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
|
||||
|
||||
fs.writeFileSync(path.join(outDir, OUTPUT_SNAPSHOT), projectionText, 'utf8');
|
||||
|
||||
// Write metadata (checksum-based provenance, no commit SHA).
|
||||
const meta = {
|
||||
schemaVersion: SCHEMA_VERSION,
|
||||
checksum,
|
||||
};
|
||||
fs.writeFileSync(
|
||||
path.join(outDir, OUTPUT_META),
|
||||
JSON.stringify(meta, null, 2) + '\n',
|
||||
'utf8'
|
||||
);
|
||||
|
||||
console.log(`Synced ${projection.length} public entries to ${outDir}/`);
|
||||
console.log(`Checksum: ${checksum}`);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
main();
|
||||
@@ -0,0 +1,34 @@
|
||||
#!/usr/bin/env node
|
||||
import fs from 'fs';
|
||||
import yaml from 'js-yaml';
|
||||
import path from 'path';
|
||||
import { fileURLToPath } from 'url';
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
const CATALOG_FILE = path.resolve(__dirname, '../../docs/feature-catalog.yaml');
|
||||
const PROHIBITED_KEYS = ['linear', 'evidence', 'internalNote', 'route', 'service'];
|
||||
|
||||
const text = fs.readFileSync(CATALOG_FILE, 'utf8');
|
||||
const doc = yaml.load(text, { schema: yaml.CORE_SCHEMA });
|
||||
|
||||
let failed = false;
|
||||
function fail(msg) { console.error('NO-LEAK FAIL: ' + msg); failed = true; }
|
||||
|
||||
if (!doc || !Array.isArray(doc.entries)) fail('catalog has no entries array');
|
||||
else {
|
||||
for (const entry of doc.entries) {
|
||||
const id = entry?.id || '(unknown)';
|
||||
for (const key of PROHIBITED_KEYS) {
|
||||
if (entry[key]) fail(`entry[${id}] contains prohibited ${key}`);
|
||||
}
|
||||
for (const [k, v] of Object.entries(entry)) {
|
||||
if (typeof v === 'string' && /SEN-[0-9]+/.test(v))
|
||||
fail(`entry[${id}] key "${k}" has SEN-NNN: "${v}"`);
|
||||
}
|
||||
if (entry.tier === 'internal' && entry.availability !== 'internal')
|
||||
fail(`entry[${id}] tier internal requires availability internal`);
|
||||
}
|
||||
}
|
||||
|
||||
if (failed) process.exit(1);
|
||||
console.log('NO-LEAK PASS');
|
||||
process.exit(0);
|
||||
Reference in New Issue
Block a user