@ctcstack/ctcdocs-core 0.1.1 → 0.2.1

package/README.md

@@ -33,5 +33,9 @@ Two properties are worth knowing about:
 [Configuration reference](https://github.com/ctcstack/ctcdocs/blob/main/docs/CONFIGURATION.md)
 · [Architecture decisions](https://github.com/ctcstack/ctcdocs/tree/main/docs/ADR)
 
-Apache-2.0. `0.x`: internal in practice, and the API may move between minor
-versions.
+All three CTCDocs packages share a version and are released together.
+What changed is in the
+[changelog](https://github.com/ctcstack/ctcdocs/blob/main/CHANGELOG.md).
+
+Apache-2.0. Internal in practice: `@ctcstack/ctcdocs` and
+`@ctcstack/ctcdocs-sync` are what a project installs.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { GENERATED_DIRECTORY_ALLOWLIST, GENERATED_FILE_ALLOWLIST, PROJECT_LAYOUT, } from './project-layout.js';
+export { GENERATED_DIRECTORY_ALLOWLIST, GENERATED_FILE_ALLOWLIST, PLATFORM_ROUTE_HREFS, PLATFORM_ROUTES, PROJECT_LAYOUT, RESERVED_SLUGS, } 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/index.js

@@ -1,4 +1,4 @@
-export { GENERATED_DIRECTORY_ALLOWLIST, GENERATED_FILE_ALLOWLIST, PROJECT_LAYOUT, } from './project-layout.js';
+export { GENERATED_DIRECTORY_ALLOWLIST, GENERATED_FILE_ALLOWLIST, PLATFORM_ROUTE_HREFS, PLATFORM_ROUTES, PROJECT_LAYOUT, RESERVED_SLUGS, } 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

@@ -31,5 +31,26 @@ export declare const PROJECT_LAYOUT: {
     readonly documentIndexFile: "data/docs-index.json";
     readonly syncReportFile: "data/latest-sync-report.json";
 };
+/**
+ * Addresses the platform serves itself.
+ *
+ * The corpus and the platform share one URL namespace, so a page the platform
+ * injects is an address no document or folder may be allocated — a document
+ * that claimed it would be silently shadowed by the route rather than fail
+ * loudly. Slug allocation reserves these the way it reserves folder slugs (see
+ * docs/ADR/014-section-index-pages.md) and validation refuses generated output
+ * that claims one.
+ *
+ * The home page is not here: `/` is not a slug any document can be allocated.
+ */
+export declare const PLATFORM_ROUTES: {
+    /** The whole corpus, grouped by folder. See docs/ADR/017-full-index-page.md. */
+    readonly fullIndex: "documents";
+};
+/** 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[];
 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

@@ -31,6 +31,27 @@ export const PROJECT_LAYOUT = {
     documentIndexFile: 'data/docs-index.json',
     syncReportFile: 'data/latest-sync-report.json',
 };
+/**
+ * Addresses the platform serves itself.
+ *
+ * The corpus and the platform share one URL namespace, so a page the platform
+ * injects is an address no document or folder may be allocated — a document
+ * that claimed it would be silently shadowed by the route rather than fail
+ * loudly. Slug allocation reserves these the way it reserves folder slugs (see
+ * docs/ADR/014-section-index-pages.md) and validation refuses generated output
+ * that claims one.
+ *
+ * The home page is not here: `/` is not a slug any document can be allocated.
+ */
+export const PLATFORM_ROUTES = {
+    /** The whole corpus, grouped by folder. See docs/ADR/017-full-index-page.md. */
+    fullIndex: 'documents',
+};
+/** 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));
 export const GENERATED_DIRECTORY_ALLOWLIST = [
     PROJECT_LAYOUT.generatedDocumentsDirectory,
     PROJECT_LAYOUT.generatedAssetsDirectory,

package/dist/site-configuration.d.ts

@@ -17,6 +17,21 @@ export interface HomeConfiguration {
      * saying, what a newcomer needs first.
      */
     readonly lede: string;
+    /**
+     * How many documents the "recently updated" band lists. The band answers
+     * "what moved since I last looked", and how far back that reaches is a
+     * property of the corpus: a wiki synchronizing a handful of documents a week
+     * needs a shorter list than one where a dozen change a day. Defaults to 6.
+     */
+    readonly recentLimit: number;
+    /**
+     * Whether the home page ends with the full index of every document, grouped
+     * by folder. Defaults to `true`. The index is published either way, at the
+     * address in `PLATFORM_ROUTES.fullIndex`; this decides only whether the home
+     * page carries a copy of it or links to it. A deployment whose corpus has
+     * outgrown one page may prefer the home page to stay an entrance.
+     */
+    readonly corpusIndex: boolean;
 }
 /**
  * Who a deployment is for.

package/dist/site-configuration.js

@@ -86,6 +86,24 @@ function flag(source, key, path) {
     }
     return value;
 }
+function optionalFlag(source, key, path, fallback) {
+    return source[key] === undefined ? fallback : flag(source, key, path);
+}
+/**
+ * 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
+ * hides it, not by a limit that leaves an empty heading behind.
+ */
+function optionalCount(source, key, path, fallback) {
+    const value = source[key];
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+        fail(path, 'must be a whole number of at least 1');
+    }
+    return value;
+}
 function optionalVisibility(source, path) {
     const value = source.visibility;
     if (value === undefined) {
@@ -164,7 +182,11 @@ export function parseSiteConfiguration(input) {
             environments: environments(deploymentSource),
             workerName,
         },
-        home: { lede: text(homeSource, 'lede', 'home.lede') },
+        home: {
+            corpusIndex: optionalFlag(homeSource, 'corpusIndex', 'home.corpusIndex', true),
+            lede: text(homeSource, 'lede', 'home.lede'),
+            recentLimit: optionalCount(homeSource, 'recentLimit', 'home.recentLimit', 6),
+        },
         navigation: {
             landingDocumentTitles: titleList(navigationSource, 'landingDocumentTitles', 'navigation.landingDocumentTitles'),
             sectionIndexPages: flag(navigationSource, 'sectionIndexPages', 'navigation.sectionIndexPages'),

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "@ctcstack/ctcdocs-core",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Configuration schema, project layout, and generated-path allowlist shared by the CTCDocs platform packages.",
+  "keywords": [
+    "ctcdocs",
+    "configuration",
+    "documentation",
+    "astro",
+    "starlight"
+  ],
   "license": "Apache-2.0",
   "type": "module",
   "repository": {
@@ -9,6 +16,13 @@
     "url": "git+https://github.com/ctcstack/ctcdocs.git",
     "directory": "packages/core"
   },
+  "homepage": "https://github.com/ctcstack/ctcdocs/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/ctcstack/ctcdocs/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",

package/src/index.ts

@@ -1,7 +1,10 @@
 export {
   GENERATED_DIRECTORY_ALLOWLIST,
   GENERATED_FILE_ALLOWLIST,
+  PLATFORM_ROUTE_HREFS,
+  PLATFORM_ROUTES,
   PROJECT_LAYOUT,
+  RESERVED_SLUGS,
 } from './project-layout.js';
 export {
   assertGeneratedPathAllowed,

package/src/project-layout.ts

@@ -32,6 +32,32 @@ export const PROJECT_LAYOUT = {
   syncReportFile: 'data/latest-sync-report.json',
 } as const;
 
+/**
+ * Addresses the platform serves itself.
+ *
+ * The corpus and the platform share one URL namespace, so a page the platform
+ * injects is an address no document or folder may be allocated — a document
+ * that claimed it would be silently shadowed by the route rather than fail
+ * loudly. Slug allocation reserves these the way it reserves folder slugs (see
+ * docs/ADR/014-section-index-pages.md) and validation refuses generated output
+ * that claims one.
+ *
+ * The home page is not here: `/` is not a slug any document can be allocated.
+ */
+export const PLATFORM_ROUTES = {
+  /** The whole corpus, grouped by folder. See docs/ADR/017-full-index-page.md. */
+  fullIndex: 'documents',
+} as const;
+
+/** Each platform route as the href a link uses. */
+export const PLATFORM_ROUTE_HREFS = {
+  fullIndex: `/${PLATFORM_ROUTES.fullIndex}/`,
+} as const;
+
+export const RESERVED_SLUGS: readonly string[] = Object.freeze(
+  Object.values(PLATFORM_ROUTES),
+);
+
 export const GENERATED_DIRECTORY_ALLOWLIST = [
   PROJECT_LAYOUT.generatedDocumentsDirectory,
   PROJECT_LAYOUT.generatedAssetsDirectory,

package/src/site-configuration.ts

@@ -36,6 +36,21 @@ export interface HomeConfiguration {
    * saying, what a newcomer needs first.
    */
   readonly lede: string;
+  /**
+   * How many documents the "recently updated" band lists. The band answers
+   * "what moved since I last looked", and how far back that reaches is a
+   * property of the corpus: a wiki synchronizing a handful of documents a week
+   * needs a shorter list than one where a dozen change a day. Defaults to 6.
+   */
+  readonly recentLimit: number;
+  /**
+   * Whether the home page ends with the full index of every document, grouped
+   * by folder. Defaults to `true`. The index is published either way, at the
+   * address in `PLATFORM_ROUTES.fullIndex`; this decides only whether the home
+   * page carries a copy of it or links to it. A deployment whose corpus has
+   * outgrown one page may prefer the home page to stay an entrance.
+   */
+  readonly corpusIndex: boolean;
 }
 
 /**
@@ -218,6 +233,36 @@ function flag(
   return value;
 }
 
+function optionalFlag(
+  source: Record<string, unknown>,
+  key: string,
+  path: string,
+  fallback: boolean,
+): boolean {
+  return source[key] === undefined ? fallback : flag(source, key, path);
+}
+
+/**
+ * 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
+ * hides it, not by a limit that leaves an empty heading behind.
+ */
+function optionalCount(
+  source: Record<string, unknown>,
+  key: string,
+  path: string,
+  fallback: number,
+): number {
+  const value = source[key];
+  if (value === undefined) {
+    return fallback;
+  }
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+    fail(path, 'must be a whole number of at least 1');
+  }
+  return value;
+}
+
 function optionalVisibility(
   source: Record<string, unknown>,
   path: string,
@@ -325,7 +370,21 @@ export function parseSiteConfiguration(input: unknown): SiteConfiguration {
       environments: environments(deploymentSource),
       workerName,
     },
-    home: { lede: text(homeSource, 'lede', 'home.lede') },
+    home: {
+      corpusIndex: optionalFlag(
+        homeSource,
+        'corpusIndex',
+        'home.corpusIndex',
+        true,
+      ),
+      lede: text(homeSource, 'lede', 'home.lede'),
+      recentLimit: optionalCount(
+        homeSource,
+        'recentLimit',
+        'home.recentLimit',
+        6,
+      ),
+    },
     navigation: {
       landingDocumentTitles: titleList(
         navigationSource,