@wxxb789/anc 0.0.1

package/scripts/validate-content.js

@@ -0,0 +1,95 @@
+/**
+ * Build gate for the generated content artifact.
+ *
+ * Runs before `astro build` so an invalid or privacy-violating artifact fails
+ * with a precise message instead of a bundler stack trace.
+ *
+ * Everything downstream of `astro build` that can *throw* is exercised here
+ * too. The build is a `&&` chain — validate, snapshot, build, redirects, Pagefind
+ * — so a throw in a later link leaves a `dist/` that is already written and now
+ * permanently incomplete, which `pnpm run preview` serves happily. Running those
+ * computations against the same artifact first means the failure happens while
+ * `dist/` is still the last known good build.
+ */
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import { REDIRECT_RULES, collectionFacets, renderRedirects, tagFacets } from "../src/lib/routes.js";
+import { ARTIFACT_PATH, loadArtifact, readArtifact } from "../src/lib/artifact-source.js";
+/**
+ * The artifact's content version: a hash of its bytes, so anything generated
+ * from it can be tied back to the exact input (requirements section 20). The
+ * artifact is already public, so its digest discloses nothing further.
+ *
+ * Exported because `emit-redirects.ts` stamps the same value into the file it
+ * writes, and two independent hashes of the same bytes is one rename away from
+ * two different stamps.
+ */
+export function contentVersion(source) {
+    return `sha256:${createHash('sha256').update(source).digest('hex')}`;
+}
+/**
+ * Run every artifact-derived computation that `astro build` and the steps after
+ * it would otherwise run for the first time, and discard the results.
+ *
+ * `tagFacets` and `collectionFacets` throw on a label with no URL-safe route key
+ * and on two labels colliding onto one key. Astro reaches them inside
+ * `getStaticPaths()`, which is after `dist/` has been opened, so the failure
+ * lands on a half-written directory. `renderRedirects` runs later still, in a
+ * separate `&&` link after `astro build` has finished writing — and if it
+ * throws, the chain stops before `pagefind --site dist` ever runs, leaving a
+ * `dist/` with no search index that `pnpm run preview` serves happily.
+ *
+ * Running all three here moves every one of those failures ahead of the first
+ * write, so a bad artifact leaves the previous good build intact.
+ *
+ * The results are deliberately unused: this is a gate, and recomputing what the
+ * pages compute would make it a second source of truth for the route set.
+ * `renderRedirects` has no failure path today — the rule set is empty and the
+ * Cloudflare rule-count ceiling went with the legacy `/<slug>/` rules. It is
+ * called anyway, because what this guards is the *ordering*: the emitter is a
+ * separate link in the `&&` chain that runs after `dist/` is written, so the
+ * day it can fail again is the day the guarantee is needed, and a call that
+ * cannot throw costs a microsecond.
+ */
+export function checkDerivedRoutes(artifact, version) {
+    tagFacets(artifact.entries);
+    collectionFacets(artifact.entries);
+    renderRedirects(REDIRECT_RULES, { schema: artifact.version, content: version });
+}
+/**
+ * Every gate this script runs, as one call, so a caller that is not the shell
+ * enforces exactly what the shell does.
+ *
+ * `bin/anc.mjs` runs the same chain in-process, and the failure
+ * mode of letting it restate the steps is that the packaged build validates less
+ * than this repository's own — a gate enforced on us and not on the people we
+ * ship to. Calling one function means there is no second list to drift.
+ *
+ * @throws {ContentValidationError} or whichever error the derived-route
+ *   computations raise, unchanged: the caller decides how to report it.
+ */
+export function validateBuildInputs(artifactPath = ARTIFACT_PATH) {
+    const artifact = loadArtifact(artifactPath);
+    checkDerivedRoutes(artifact, contentVersion(readArtifact(artifactPath)));
+    return artifact;
+}
+/**
+ * @param artifactPath Artifact to validate, repository-relative. Defaults to
+ *   whichever one this build selected — `src/data/content.json` unless
+ *   `CONTENT_ARTIFACT` names another. A caller passes a path so it can gate a
+ *   candidate artifact without writing over `src/data/content.json`, which is
+ *   producer-owned generated content.
+ */
+function main(artifactPath = ARTIFACT_PATH) {
+    try {
+        const artifact = validateBuildInputs(artifactPath);
+        console.log(`content ok: version=${artifact.version} entries=${artifact.entries.length}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+if (process.argv[1] === fileURLToPath(import.meta.url))
+    process.exit(main(process.argv[2]));

package/scripts/vendor-provenance.js

@@ -0,0 +1,307 @@
+/**
+ * Build-minted provenance for JavaScript chunks containing dependency code only.
+ *
+ * The final residue scan must keep reading every first-party chunk, while the
+ * selected client runtimes emit dependency chunks containing byte sequences
+ * that resemble residue. A basename cannot prove which is which. The bundler can: its chunk
+ * interface carries every resolved module id before the bytes are written.
+ *
+ * The manifest lives beside, never inside, the output directory. It therefore
+ * reaches the scanner in the next process without becoming a public asset. It
+ * contains final output names only — never module ids or host paths.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve, sep, win32 } from 'node:path';
+import { BuildFailure } from "./write-report.js";
+export const VENDOR_PROVENANCE_VERSION = 2;
+export const VENDOR_STATE_SUFFIX = '.publish-state';
+export const VENDOR_PROVENANCE_FILE = 'vendored-chunks.json';
+export const CLIENT_ASSET_PREFIX = '_astro/';
+function slash(path) {
+    return path.replaceAll('\\', '/').replace(/\/$/, '');
+}
+function canonical(path) {
+    // A Windows absolute module ID stays absolute when inspected on POSIX; the
+    // host's resolve() would otherwise prefix cwd to e.g. Q:/repo/module.js.
+    const windowsPath = /^[a-z]:[\\/]/i.test(path) || path.startsWith('\\\\');
+    if (windowsPath && process.platform !== 'win32') {
+        return slash(win32.normalize(path)).toLowerCase();
+    }
+    const absolute = resolve(path);
+    const real = slash(existsSync(absolute) ? realpathSync(absolute) : absolute);
+    // Distinct case-sensitive POSIX directories must not receive the same grant.
+    return process.platform === 'win32' ? real.toLowerCase() : real;
+}
+/** Package owners measured in the selected Mermaid and Temml client bundles. */
+export const CLIENT_RUNTIME_PACKAGES = new Set([
+    '@braintree/sanitize-url',
+    '@iconify/utils',
+    '@mermaid-js/parser',
+    '@upsetjs/venn.js',
+    'cose-base',
+    'cytoscape',
+    'cytoscape-cose-bilkent',
+    'cytoscape-fcose',
+    'd3',
+    'd3-array',
+    'd3-axis',
+    'd3-brush',
+    'd3-color',
+    'd3-dispatch',
+    'd3-ease',
+    'd3-format',
+    'd3-hierarchy',
+    'd3-interpolate',
+    'd3-path',
+    'd3-sankey',
+    'd3-scale',
+    'd3-scale-chromatic',
+    'd3-selection',
+    'd3-shape',
+    'd3-time',
+    'd3-time-format',
+    'd3-timer',
+    'd3-transition',
+    'd3-zoom',
+    'dagre-d3-es',
+    'dayjs',
+    'dompurify',
+    'elkjs',
+    'es-toolkit',
+    'internmap',
+    'katex',
+    'khroma',
+    'layout-base',
+    'lodash-es',
+    'marked',
+    'mermaid',
+    'roughjs',
+    'stylis',
+    'temml',
+    'ts-dedent',
+    'uuid',
+]);
+/** The one generated module measured inside an otherwise-vendored Rolldown chunk. */
+const TRUSTED_BUNDLER_MODULES = new Set(['\0rolldown/runtime.js']);
+function packageAt(entry) {
+    let directory = dirname(entry);
+    while (true) {
+        const manifestPath = join(directory, 'package.json');
+        if (existsSync(manifestPath)) {
+            try {
+                const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+                if (typeof manifest.name === 'string')
+                    return { root: directory, manifest, manifestPath };
+            }
+            catch (error) {
+                return refuse('could not read runtime package metadata: ' + String(error));
+            }
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            return refuse('could not locate package metadata for a client runtime module');
+        directory = parent;
+    }
+}
+/**
+ * Canonical roots in the installed Mermaid/Temml dependency closure that this
+ * build is allowed to classify as vendored. Package names remain an explicit
+ * review list; resolution supplies the stronger fact that a module came from
+ * the exact package instance these runtimes load, not a same-named external tree.
+ */
+export function clientRuntimePackageRoots(packageRoot) {
+    const roots = new Set();
+    const visited = new Set();
+    const visit = (name, importer, required) => {
+        let entry;
+        try {
+            entry = createRequire(importer).resolve(name);
+        }
+        catch (error) {
+            // Some browser-only packages deliberately expose no Node main. The package
+            // manager link beside the importing package still identifies the exact
+            // installed instance Vite resolves; use its manifest, never a name search
+            // elsewhere in the tree.
+            const linkedManifest = join(dirname(dirname(importer)), ...name.split('/'), 'package.json');
+            if (existsSync(linkedManifest))
+                entry = linkedManifest;
+            else {
+                if (!required)
+                    return;
+                return refuse('could not resolve selected client runtime ' + name + ': ' + String(error));
+            }
+        }
+        const resolved = packageAt(entry);
+        const packageRoot = canonical(resolved.root);
+        if (visited.has(packageRoot))
+            return;
+        visited.add(packageRoot);
+        if (resolved.manifest.name !== undefined && CLIENT_RUNTIME_PACKAGES.has(resolved.manifest.name)) {
+            roots.add(packageRoot);
+        }
+        for (const dependency of Object.keys(resolved.manifest.dependencies ?? {})) {
+            visit(dependency, resolved.manifestPath, false);
+        }
+        for (const dependency of Object.keys(resolved.manifest.optionalDependencies ?? {})) {
+            visit(dependency, resolved.manifestPath, false);
+        }
+    };
+    const importer = join(resolve(packageRoot), 'package.json');
+    visit('mermaid', importer, true);
+    visit('temml', importer, true);
+    return [...roots].sort();
+}
+/** Every non-virtual module must be inside one exact resolved runtime root. */
+export function isVendoredChunk(moduleIds, trustedRoots) {
+    if (moduleIds.length === 0)
+        return false;
+    let packages = 0;
+    for (const id of moduleIds) {
+        const withoutQuery = id.split('?')[0];
+        if (withoutQuery.startsWith('\0')) {
+            if (!TRUSTED_BUNDLER_MODULES.has(withoutQuery))
+                return false;
+            continue;
+        }
+        const modulePath = canonical(withoutQuery);
+        if (!trustedRoots.some((root) => modulePath === root || modulePath.startsWith(root + '/')))
+            return false;
+        packages += 1;
+    }
+    return packages > 0;
+}
+/** Final client chunk names whose module ownership is dependency-only. */
+export function vendoredClientChunks(chunks, trustedRoots) {
+    return [...new Set(chunks
+            .filter((chunk) => chunk.fileName.startsWith(CLIENT_ASSET_PREFIX))
+            .filter((chunk) => isVendoredChunk(chunk.moduleIds, trustedRoots))
+            .map((chunk) => chunk.fileName))].sort();
+}
+/**
+ * Vite/Rolldown adapter that writes exact provenance after client chunks exist.
+ *
+ * Astro invokes output hooks for more than one bundle. State is isolated by
+ * output directory and only a bundle carrying client JavaScript can write, so a
+ * later server bundle cannot erase the client result. Repeated client outputs
+ * union rather than replace their observations.
+ */
+export function vendorProvenancePlugin(packageRoot) {
+    const byOutDir = new Map();
+    let trustedRoots;
+    return {
+        name: 'publish:vendor-provenance',
+        apply: 'build',
+        enforce: 'post',
+        writeBundle(options, bundle) {
+            const clientChunks = Object.values(bundle).filter((output) => output.type === 'chunk' &&
+                output.fileName.startsWith(CLIENT_ASSET_PREFIX) &&
+                Array.isArray(output.moduleIds));
+            if (clientChunks.length === 0)
+                return;
+            if (options.dir === undefined)
+                return refuse('the client bundle declares no output directory');
+            const outDir = resolve(options.dir);
+            const observed = byOutDir.get(outDir) ?? new Map();
+            byOutDir.set(outDir, observed);
+            for (const chunk of clientChunks) {
+                observed.set(chunk.fileName, { fileName: chunk.fileName, moduleIds: chunk.moduleIds });
+            }
+            trustedRoots ??= clientRuntimePackageRoots(packageRoot);
+            writeVendorProvenance(outDir, vendoredClientChunks([...observed.values()], trustedRoots));
+        },
+    };
+}
+/** The non-public, output-specific manifest paired with one output directory. */
+export function vendorProvenancePath(outDir) {
+    return join(resolve(outDir) + VENDOR_STATE_SUFFIX, VENDOR_PROVENANCE_FILE);
+}
+function refuse(detail) {
+    throw new BuildFailure('vendor-provenance-invalid', 'vendored chunk provenance is invalid — rebuild the site before scanning it', detail);
+}
+function validateChunkPath(path) {
+    if (typeof path !== 'string' || !/^_astro\/[^/]+\.js$/.test(path)) {
+        return refuse('vendored chunk provenance carries an invalid output name: ' + JSON.stringify(path));
+    }
+    return path;
+}
+function sha256(path) {
+    return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+function validateGrant(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return refuse('vendored chunk provenance carries a non-object grant');
+    }
+    const grant = value;
+    if (Object.keys(grant).sort().join(',') !== 'file,sha256') {
+        return refuse('vendored chunk provenance grant does not have exactly file and sha256');
+    }
+    const file = validateChunkPath(grant['file']);
+    if (typeof grant['sha256'] !== 'string' || !/^[a-f0-9]{64}$/.test(grant['sha256'])) {
+        return refuse('vendored chunk provenance carries an invalid SHA-256 digest');
+    }
+    return { file, sha256: grant['sha256'] };
+}
+/** Write one complete, deterministic, content-bound manifest. */
+export function writeVendorProvenance(outDir, chunks) {
+    const path = vendorProvenancePath(outDir);
+    const files = [...new Set(chunks.map(validateChunkPath))].sort();
+    const grants = files.map((file) => {
+        const candidate = join(outDir, ...file.split('/'));
+        if (!existsSync(candidate) || !statSync(candidate).isFile()) {
+            return refuse('cannot grant a vendored chunk that is not in this output');
+        }
+        return { file, sha256: sha256(candidate) };
+    });
+    const body = { version: VENDOR_PROVENANCE_VERSION, chunks: grants };
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = path + '.' + process.pid + '.tmp';
+    writeFileSync(temporary, JSON.stringify(body, null, 2) + '\n', 'utf8');
+    renameSync(temporary, path);
+}
+export function readVendorProvenance(root, options = {}) {
+    const path = options.path ?? vendorProvenancePath(root);
+    if (!existsSync(path)) {
+        if (options.required === true)
+            return refuse('the client build wrote no vendored chunk provenance');
+        return new Set();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        return refuse('could not parse ' + path + ': ' + (error instanceof Error ? error.message : String(error)));
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed) ||
+        Object.keys(parsed).sort().join(',') !== 'chunks,version') {
+        return refuse(path + ' does not have exactly the version and chunks keys');
+    }
+    const record = parsed;
+    if (record['version'] !== VENDOR_PROVENANCE_VERSION || !Array.isArray(record['chunks'])) {
+        return refuse(path + ' has an unsupported version or a non-array chunks value');
+    }
+    const grants = record['chunks'].map(validateGrant);
+    const files = grants.map((grant) => grant.file);
+    if (new Set(files).size !== files.length || [...files].sort().some((value, index) => value !== files[index])) {
+        return refuse(path + ' chunk names are duplicated or not sorted');
+    }
+    if (options.required === true && grants.length === 0) {
+        return refuse(path + ' grants no chunks to a client diagram build');
+    }
+    for (const grant of grants) {
+        const candidate = join(root, ...grant.file.split('/'));
+        if (!existsSync(candidate) || !statSync(candidate).isFile()) {
+            return refuse(path + ' names a file that is not in the built site');
+        }
+        const relative = candidate.slice(resolve(root).length + 1);
+        if (relative.split(sep).join('/') !== grant.file) {
+            return refuse(path + ' names a file that does not resolve inside the built site');
+        }
+        if (sha256(candidate) !== grant.sha256) {
+            return refuse(path + ' does not describe the bytes in this build');
+        }
+    }
+    return new Set(files);
+}