@ctcstack/ctcdocs-core 0.5.2 → 0.7.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { GENERATED_DIRECTORY_ALLOWLIST, GENERATED_FILE_ALLOWLIST, PLATFORM_ROUTE_HREFS, PLATFORM_ROUTES, PROJECT_LAYOUT, RESERVED_SLUGS, } from './project-layout.js';
+export { GENERATED_DIRECTORY_ALLOWLIST, GENERATED_FILE_ALLOWLIST, PLATFORM_ROUTE_HREFS, PLATFORM_ROUTES, permanentLinkPath, PROJECT_LAYOUT, RESERVED_SLUGS, SHORT_ID_PATTERN, } from './project-layout.js';
 export { assertGeneratedPathAllowed, isGeneratedPathAllowed, normalizeRepositoryPath, } from './generated-paths.js';
 export { generatedMarkdownHeader, generatedSourceHeader, } from './ownership-markers.js';
 export { findProjectRoot, ProjectRootError } from './project-root.js';
 export { loadSiteConfiguration, parseSiteConfiguration, SiteConfigurationError, } from './site-configuration.js';
-export type { BrandConfiguration, DeploymentConfiguration, DeploymentEnvironmentConfiguration, DeploymentEnvironmentConfigurations, DeploymentVisibility, HomeConfiguration, NavigationConfiguration, SiteConfiguration, SyncConfigurationDefaults, } from './site-configuration.js';
+export type { AddressPolicy, BrandConfiguration, DeploymentConfiguration, DeploymentEnvironmentConfiguration, DeploymentEnvironmentConfigurations, DeploymentVisibility, HomeConfiguration, NavigationConfiguration, SiteConfiguration, SyncConfigurationDefaults, } from './site-configuration.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { GENERATED_DIRECTORY_ALLOWLIST, GENERATED_FILE_ALLOWLIST, PLATFORM_ROUTE_HREFS, PLATFORM_ROUTES, PROJECT_LAYOUT, RESERVED_SLUGS, } from './project-layout.js';
+export { GENERATED_DIRECTORY_ALLOWLIST, GENERATED_FILE_ALLOWLIST, PLATFORM_ROUTE_HREFS, PLATFORM_ROUTES, permanentLinkPath, PROJECT_LAYOUT, RESERVED_SLUGS, SHORT_ID_PATTERN, } from './project-layout.js';
 export { assertGeneratedPathAllowed, isGeneratedPathAllowed, normalizeRepositoryPath, } from './generated-paths.js';
 export { generatedMarkdownHeader, generatedSourceHeader, } from './ownership-markers.js';
 export { findProjectRoot, ProjectRootError } from './project-root.js';

package/dist/project-layout.d.ts

@@ -46,11 +46,24 @@ export declare const PROJECT_LAYOUT: {
 export declare const PLATFORM_ROUTES: {
     /** The whole corpus, grouped by folder. See docs/ADR/017-full-index-page.md. */
     readonly fullIndex: "documents";
+    /**
+     * Permanent links, `/d/<short ID>/`, one per document and section. See
+     * docs/ADR/022-permanent-short-ids.md.
+     */
+    readonly permanentLinks: "d";
 };
 /** Each platform route as the href a link uses. */
 export declare const PLATFORM_ROUTE_HREFS: {
     readonly fullIndex: "/documents/";
 };
 export declare const RESERVED_SLUGS: readonly string[];
+/**
+ * A short ID: lowercase hexadecimal, six characters unless six collided with
+ * another item's, in which case it is longer. It is recorded once per item and
+ * never changes, so a permanent link keeps working through every rename.
+ */
+export declare const SHORT_ID_PATTERN: RegExp;
+/** The site-relative permanent link of an item with this short ID. */
+export declare function permanentLinkPath(shortId: string): string;
 export declare const GENERATED_DIRECTORY_ALLOWLIST: readonly ["src/content/docs/_generated", "src/assets/generated", "src/generated"];
 export declare const GENERATED_FILE_ALLOWLIST: readonly ["data/sync-manifest.json", "data/docs-index.json", "data/latest-sync-report.json"];

package/dist/project-layout.js

@@ -46,12 +46,27 @@ export const PROJECT_LAYOUT = {
 export const PLATFORM_ROUTES = {
     /** The whole corpus, grouped by folder. See docs/ADR/017-full-index-page.md. */
     fullIndex: 'documents',
+    /**
+     * Permanent links, `/d/<short ID>/`, one per document and section. See
+     * docs/ADR/022-permanent-short-ids.md.
+     */
+    permanentLinks: 'd',
 };
 /** Each platform route as the href a link uses. */
 export const PLATFORM_ROUTE_HREFS = {
     fullIndex: `/${PLATFORM_ROUTES.fullIndex}/`,
 };
 export const RESERVED_SLUGS = Object.freeze(Object.values(PLATFORM_ROUTES));
+/**
+ * A short ID: lowercase hexadecimal, six characters unless six collided with
+ * another item's, in which case it is longer. It is recorded once per item and
+ * never changes, so a permanent link keeps working through every rename.
+ */
+export const SHORT_ID_PATTERN = /^[0-9a-f]{6,64}$/u;
+/** The site-relative permanent link of an item with this short ID. */
+export function permanentLinkPath(shortId) {
+    return `/${PLATFORM_ROUTES.permanentLinks}/${shortId}/`;
+}
 export const GENERATED_DIRECTORY_ALLOWLIST = [
     PROJECT_LAYOUT.generatedDocumentsDirectory,
     PROJECT_LAYOUT.generatedAssetsDirectory,

package/dist/site-configuration.d.ts

@@ -100,7 +100,25 @@ export interface NavigationConfiguration {
      * slugs are reserved either way, so turning this on or off moves no address.
      */
     readonly sectionIndexPages: boolean;
+    /**
+     * The Unicode scripts a letter in a Drive name may belong to, such as
+     * `["Latin"]`, or `null` when any script is accepted. A name becomes a
+     * heading, a sidebar label and, once, a permanent address, so a deployment
+     * whose editors write in one alphabet can refuse a letter typed on the other
+     * keyboard layout before it reaches any of them. Whatever this allows, a
+     * single word never mixes Latin, Cyrillic and Greek letters (ADR-020).
+     */
+    readonly nameScripts: readonly string[] | null;
+    /**
+     * Whether an address stays where it was first given (`stable`, ADR-005) or
+     * follows its item's current Drive path on every sync over the whole corpus
+     * (`follow-names`, ADR-021). Either way a moved address leaves a redirect,
+     * so a project can switch while its structure settles and back once people
+     * share links. Defaults to `stable`.
+     */
+    readonly addresses: AddressPolicy;
 }
+export type AddressPolicy = 'stable' | 'follow-names';
 export interface SiteConfiguration {
     readonly brand: BrandConfiguration;
     readonly deployment: DeploymentConfiguration;

package/dist/site-configuration.js

@@ -89,6 +89,36 @@ function flag(source, key, path) {
 function optionalFlag(source, key, path, fallback) {
     return source[key] === undefined ? fallback : flag(source, key, path);
 }
+/**
+ * A list of distinct Unicode script names, as a `\p{Script=…}` property
+ * escape spells them. Each name is proved by compiling that escape, so a typo
+ * fails here rather than letting every letter through, or none.
+ */
+function optionalScriptList(source, key, path) {
+    const value = source[key];
+    if (value === undefined) {
+        return null;
+    }
+    if (!Array.isArray(value) || value.length === 0) {
+        fail(path, 'must be a non-empty array of Unicode script names');
+    }
+    const scripts = value.map((entry, index) => {
+        if (typeof entry !== 'string' || !/^[A-Za-z_]+$/u.test(entry)) {
+            fail(`${path}[${index}]`, 'must be a Unicode script name such as "Latin"');
+        }
+        try {
+            new RegExp(`\\p{Script=${entry}}`, 'u');
+        }
+        catch {
+            fail(`${path}[${index}]`, 'must be a Unicode script name such as "Latin"');
+        }
+        return entry;
+    });
+    if (new Set(scripts).size !== scripts.length) {
+        fail(path, 'must not repeat a script');
+    }
+    return Object.freeze(scripts);
+}
 /**
  * A count of things shown on a page. Zero is rejected along with fractions and
  * negatives: a block configured to show nothing is hidden by the switch that
@@ -104,6 +134,16 @@ function optionalCount(source, key, path, fallback) {
     }
     return value;
 }
+function optionalAddressPolicy(source, key, path) {
+    const value = source[key];
+    if (value === undefined) {
+        return 'stable';
+    }
+    if (value !== 'stable' && value !== 'follow-names') {
+        fail(path, 'must be "stable" or "follow-names"');
+    }
+    return value;
+}
 function optionalVisibility(source, path) {
     const value = source.visibility;
     if (value === undefined) {
@@ -190,6 +230,8 @@ export function parseSiteConfiguration(input) {
         navigation: {
             landingDocumentTitles: titleList(navigationSource, 'landingDocumentTitles', 'navigation.landingDocumentTitles'),
             sectionIndexPages: flag(navigationSource, 'sectionIndexPages', 'navigation.sectionIndexPages'),
+            nameScripts: optionalScriptList(navigationSource, 'nameScripts', 'navigation.nameScripts'),
+            addresses: optionalAddressPolicy(navigationSource, 'addresses', 'navigation.addresses'),
         },
         sync: {
             commitBotName: text(syncSource, 'commitBotName', 'sync.commitBotName'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctcstack/ctcdocs-core",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "Configuration schema, project layout, and generated-path allowlist shared by the CTCDocs platform packages.",
   "keywords": [
     "ctcdocs",

package/src/index.ts

@@ -3,8 +3,10 @@ export {
   GENERATED_FILE_ALLOWLIST,
   PLATFORM_ROUTE_HREFS,
   PLATFORM_ROUTES,
+  permanentLinkPath,
   PROJECT_LAYOUT,
   RESERVED_SLUGS,
+  SHORT_ID_PATTERN,
 } from './project-layout.js';
 export {
   assertGeneratedPathAllowed,
@@ -22,6 +24,7 @@ export {
   SiteConfigurationError,
 } from './site-configuration.js';
 export type {
+  AddressPolicy,
   BrandConfiguration,
   DeploymentConfiguration,
   DeploymentEnvironmentConfiguration,

package/src/project-layout.ts

@@ -47,6 +47,11 @@ export const PROJECT_LAYOUT = {
 export const PLATFORM_ROUTES = {
   /** The whole corpus, grouped by folder. See docs/ADR/017-full-index-page.md. */
   fullIndex: 'documents',
+  /**
+   * Permanent links, `/d/<short ID>/`, one per document and section. See
+   * docs/ADR/022-permanent-short-ids.md.
+   */
+  permanentLinks: 'd',
 } as const;
 
 /** Each platform route as the href a link uses. */
@@ -58,6 +63,18 @@ export const RESERVED_SLUGS: readonly string[] = Object.freeze(
   Object.values(PLATFORM_ROUTES),
 );
 
+/**
+ * A short ID: lowercase hexadecimal, six characters unless six collided with
+ * another item's, in which case it is longer. It is recorded once per item and
+ * never changes, so a permanent link keeps working through every rename.
+ */
+export const SHORT_ID_PATTERN = /^[0-9a-f]{6,64}$/u;
+
+/** The site-relative permanent link of an item with this short ID. */
+export function permanentLinkPath(shortId: string): string {
+  return `/${PLATFORM_ROUTES.permanentLinks}/${shortId}/`;
+}
+
 export const GENERATED_DIRECTORY_ALLOWLIST = [
   PROJECT_LAYOUT.generatedDocumentsDirectory,
   PROJECT_LAYOUT.generatedAssetsDirectory,

package/src/site-configuration.ts

@@ -125,8 +125,27 @@ export interface NavigationConfiguration {
    * slugs are reserved either way, so turning this on or off moves no address.
    */
   readonly sectionIndexPages: boolean;
+  /**
+   * The Unicode scripts a letter in a Drive name may belong to, such as
+   * `["Latin"]`, or `null` when any script is accepted. A name becomes a
+   * heading, a sidebar label and, once, a permanent address, so a deployment
+   * whose editors write in one alphabet can refuse a letter typed on the other
+   * keyboard layout before it reaches any of them. Whatever this allows, a
+   * single word never mixes Latin, Cyrillic and Greek letters (ADR-020).
+   */
+  readonly nameScripts: readonly string[] | null;
+  /**
+   * Whether an address stays where it was first given (`stable`, ADR-005) or
+   * follows its item's current Drive path on every sync over the whole corpus
+   * (`follow-names`, ADR-021). Either way a moved address leaves a redirect,
+   * so a project can switch while its structure settles and back once people
+   * share links. Defaults to `stable`.
+   */
+  readonly addresses: AddressPolicy;
 }
 
+export type AddressPolicy = 'stable' | 'follow-names';
+
 export interface SiteConfiguration {
   readonly brand: BrandConfiguration;
   readonly deployment: DeploymentConfiguration;
@@ -242,6 +261,46 @@ function optionalFlag(
   return source[key] === undefined ? fallback : flag(source, key, path);
 }
 
+/**
+ * A list of distinct Unicode script names, as a `\p{Script=…}` property
+ * escape spells them. Each name is proved by compiling that escape, so a typo
+ * fails here rather than letting every letter through, or none.
+ */
+function optionalScriptList(
+  source: Record<string, unknown>,
+  key: string,
+  path: string,
+): readonly string[] | null {
+  const value = source[key];
+  if (value === undefined) {
+    return null;
+  }
+  if (!Array.isArray(value) || value.length === 0) {
+    fail(path, 'must be a non-empty array of Unicode script names');
+  }
+  const scripts = value.map((entry, index) => {
+    if (typeof entry !== 'string' || !/^[A-Za-z_]+$/u.test(entry)) {
+      fail(
+        `${path}[${index}]`,
+        'must be a Unicode script name such as "Latin"',
+      );
+    }
+    try {
+      new RegExp(`\\p{Script=${entry}}`, 'u');
+    } catch {
+      fail(
+        `${path}[${index}]`,
+        'must be a Unicode script name such as "Latin"',
+      );
+    }
+    return entry;
+  });
+  if (new Set(scripts).size !== scripts.length) {
+    fail(path, 'must not repeat a script');
+  }
+  return Object.freeze(scripts);
+}
+
 /**
  * A count of things shown on a page. Zero is rejected along with fractions and
  * negatives: a block configured to show nothing is hidden by the switch that
@@ -263,6 +322,21 @@ function optionalCount(
   return value;
 }
 
+function optionalAddressPolicy(
+  source: Record<string, unknown>,
+  key: string,
+  path: string,
+): AddressPolicy {
+  const value = source[key];
+  if (value === undefined) {
+    return 'stable';
+  }
+  if (value !== 'stable' && value !== 'follow-names') {
+    fail(path, 'must be "stable" or "follow-names"');
+  }
+  return value;
+}
+
 function optionalVisibility(
   source: Record<string, unknown>,
   path: string,
@@ -396,6 +470,16 @@ export function parseSiteConfiguration(input: unknown): SiteConfiguration {
         'sectionIndexPages',
         'navigation.sectionIndexPages',
       ),
+      nameScripts: optionalScriptList(
+        navigationSource,
+        'nameScripts',
+        'navigation.nameScripts',
+      ),
+      addresses: optionalAddressPolicy(
+        navigationSource,
+        'addresses',
+        'navigation.addresses',
+      ),
     },
     sync: {
       commitBotName: text(syncSource, 'commitBotName', 'sync.commitBotName'),