@ctcstack/ctcdocs-core 0.6.0 → 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

@@ -109,7 +109,16 @@ export interface NavigationConfiguration {
      * 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

@@ -134,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) {
@@ -221,6 +231,7 @@ export function parseSiteConfiguration(input) {
             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.6.0",
+  "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

@@ -134,8 +134,18 @@ export interface NavigationConfiguration {
    * 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;
@@ -312,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,
@@ -450,6 +475,11 @@ export function parseSiteConfiguration(input: unknown): SiteConfiguration {
         'nameScripts',
         'navigation.nameScripts',
       ),
+      addresses: optionalAddressPolicy(
+        navigationSource,
+        'addresses',
+        'navigation.addresses',
+      ),
     },
     sync: {
       commitBotName: text(syncSource, 'commitBotName', 'sync.commitBotName'),